From 463c1273c202f7c10edf746a672b3c3a8fb37ba0 Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Mon, 22 Jun 2026 17:06:36 +0000
Subject: [PATCH 01/10] extract reusable functions from plainTextView

---
 .../react/src/test/text/plainUtils.test.ts    | 105 +++++++++++-
 .../framework/react/src/text/plain/index.ts   |   8 +-
 .../react/src/text/plain/plainTextView.tsx    |  81 ++-------
 .../react/src/text/plain/plainUtils.ts        | 158 +++++++++++++++++-
 4 files changed, 281 insertions(+), 71 deletions(-)

diff --git a/packages/framework/react/src/test/text/plainUtils.test.ts b/packages/framework/react/src/test/text/plainUtils.test.ts
index 21a9ba1782d4..5057e267c642 100644
--- a/packages/framework/react/src/test/text/plainUtils.test.ts
+++ b/packages/framework/react/src/test/text/plainUtils.test.ts
@@ -5,11 +5,114 @@
 
 import { strict as assert } from "node:assert";
 
+import { TextAsTree } from "@fluidframework/tree/internal";
+import {
+	independentView,
+	TreeViewConfiguration,
+	type TreeViewAlpha,
+} from "@fluidframework/tree/alpha";
+
+import { createUndoRedo } from "../../undoRedo.js";
 // Allow import of file being tested
 // eslint-disable-next-line import-x/no-internal-modules
-import { computeSync } from "../../text/plain/plainUtils.js";
+import { applyTextEdit, applyTextOps, computeSync } from "../../text/plain/plainUtils.js";
 
 describe("plainUtils", () => {
+	describe("applyTextOps", () => {
+		it("inserts text, leaving the selection start before the edit and extending the end past it", () => {
+			// "hello" with selection "el" (1-3); insert "XX" at index 2, inside the selection.
+			// start (before the insert) is unchanged; end (after it) shifts by the inserted length.
+			const result = applyTextOps("hello", { start: 1, end: 3 }, [
+				{ type: "retain", count: 2 },
+				{ type: "insert", text: "XX" },
+				{ type: "retain", count: 3 },
+			]);
+			assert.deepEqual(result, { value: "heXXllo", selection: { start: 1, end: 5 } });
+		});
+
+		it("removes text, clamping a selection start inside the removal and pulling back the end after it", () => {
+			// "hello" with selection "llo" (2-5); remove "ell" (1-4).
+			// start sits inside the removal and clamps to its start; end is past it and pulls back.
+			const result = applyTextOps("hello", { start: 2, end: 5 }, [
+				{ type: "retain", count: 1 },
+				{ type: "remove", count: 3 },
+				{ type: "retain", count: 1 },
+			]);
+			assert.deepEqual(result, { value: "ho", selection: { start: 1, end: 2 } });
+		});
+
+		it("treats op counts as code points, not UTF-16 units, for astral characters", () => {
+			// "😀" is one code point but two UTF-16 units. Retain it, then insert after.
+			const value = "😀x";
+			// Cursor was at end (3 UTF-16 units); the insert is before it, so it shifts by 1.
+			const result = applyTextOps(value, { start: value.length, end: value.length }, [
+				{ type: "retain", count: 1 },
+				{ type: "insert", text: "Y" },
+				{ type: "retain", count: 1 },
+			]);
+			assert.deepEqual(result, { value: "😀Yx", selection: { start: 4, end: 4 } });
+		});
+
+		it("appends the tail of the old value not covered by trailing ops", () => {
+			const result = applyTextOps("hello", { start: 0, end: 0 }, [
+				{ type: "retain", count: 2 },
+			]);
+			assert.deepEqual(result, { value: "hello", selection: { start: 0, end: 0 } });
+		});
+
+		it("clamps a stale selection that lands outside the new value", () => {
+			// Selection points past the end of oldValue; after a shrinking edit it must not exceed value.length.
+			const result = applyTextOps("hello", { start: 10, end: 10 }, [
+				{ type: "remove", count: 3 },
+				{ type: "retain", count: 2 },
+			]);
+			assert.deepEqual(result, { value: "lo", selection: { start: 2, end: 2 } });
+		});
+	});
+
+	describe("applyTextEdit", () => {
+		function createTextView(initial: string): TreeViewAlpha<typeof TextAsTree.Tree> {
+			const view = independentView(new TreeViewConfiguration({ schema: TextAsTree.Tree }));
+			view.initialize(TextAsTree.Tree.fromString(initial));
+			return view;
+		}
+
+		it("applies the edit directly to an unhydrated (non-branch) node", () => {
+			const root = TextAsTree.Tree.fromString("hello");
+			applyTextEdit(root, "hello world");
+			assert.equal(root.fullString(), "hello world");
+		});
+
+		it("wraps the edit in a transaction tagged with the given label when on a branch", () => {
+			const view = createTextView("hello");
+			const label = Symbol("editor");
+			const manager = createUndoRedo(view);
+
+			applyTextEdit(view.root, "hello world", label);
+			assert.equal(view.root.fullString(), "hello world");
+
+			// The edit was a single transaction tagged with `label`, so a label-scoped undo
+			// reverts the whole edit in one step.
+			assert(manager.canUndo(label));
+			manager.undo(label);
+			assert.equal(view.root.fullString(), "hello");
+			manager.dispose();
+		});
+
+		it("defaults the transaction label to the root node when none is given", () => {
+			const view = createTextView("hello");
+			const manager = createUndoRedo(view);
+
+			applyTextEdit(view.root, "hello world");
+
+			// With no explicit label, the edit is tagged with `root` itself.
+			assert(manager.canUndo(view.root));
+			manager.undo(view.root);
+			assert.equal(view.root.fullString(), "hello");
+			manager.dispose();
+		});
+	});
+
 	describe("computeSync", () => {
 		/**
 		 * Calls computeSync, applies the returned ops to a copy of `existing`,
diff --git a/packages/framework/react/src/text/plain/index.ts b/packages/framework/react/src/text/plain/index.ts
index 91cf8ed288c0..271d43a66ce2 100644
--- a/packages/framework/react/src/text/plain/index.ts
+++ b/packages/framework/react/src/text/plain/index.ts
@@ -7,4 +7,10 @@ export {
 	MainView as PlainTextMainView,
 	type MainViewProps as PlainTextMainViewProps,
 } from "./plainTextView.js";
-export { syncTextToTree } from "./plainUtils.js";
+export {
+	applyTextEdit,
+	applyTextOps,
+	type ApplyTextOpsResult,
+	syncTextToTree,
+	type TextSelection,
+} from "./plainUtils.js";
diff --git a/packages/framework/react/src/text/plain/plainTextView.tsx b/packages/framework/react/src/text/plain/plainTextView.tsx
index 3d52fdb29364..68d926cae7e6 100644
--- a/packages/framework/react/src/text/plain/plainTextView.tsx
+++ b/packages/framework/react/src/text/plain/plainTextView.tsx
@@ -3,17 +3,13 @@
  * Licensed under the MIT License.
  */
 
-import {
-	type TextAsTree,
-	TreeAlpha,
-	utf16LengthForCodePoints,
-} from "@fluidframework/tree/internal";
+import type { TextAsTree } from "@fluidframework/tree/internal";
 import { type ChangeEvent, type FC, useCallback, useEffect, useReducer, useRef } from "react";
 
 import { unwrapPropTreeNode, type PropTreeNode } from "../../propNode.js";
 import type { TextEditorProps } from "../textEditorProps.js";
 
-import { syncTextToTree } from "./plainUtils.js";
+import { applyTextEdit, applyTextOps, type TextSelection } from "./plainUtils.js";
 
 /**
  * Props for the MainView component.
@@ -76,70 +72,27 @@ const PlainTextEditorView: FC<MainViewPropsInner> = ({ root, undoRedo, editLabel
 			try {
 				const textarea = textareaRef.current;
 				let newValue: string;
-				let newCursorStart: number | undefined;
-				let newCursorEnd: number | undefined;
+				let newSelection: TextSelection | undefined;
 				if (ops === undefined) {
 					// Delta unavailable — fall back to full re-read.
 					newValue = root.fullString();
 				} else {
 					// Apply ops incrementally to avoid a full O(N) re-read.
-					const selectionStart = textarea.selectionStart;
-					const selectionEnd = textarea.selectionEnd;
-
-					// readPos is a UTF-16 code-unit index into oldValue.
-					// op.count is in Unicode code points; we convert via utf16LengthForCodePoints.
-					let readPos = 0;
-					const oldValue = textarea.value;
-					newValue = "";
-					newCursorStart = selectionStart;
-					newCursorEnd = selectionEnd;
-
-					for (const op of ops) {
-						if (op.type === "retain") {
-							// Convert atom count to UTF-16 units by scanning the actual characters.
-							const utf16Count = utf16LengthForCodePoints(oldValue, readPos, op.count);
-							newValue += oldValue.slice(readPos, readPos + utf16Count);
-							readPos += utf16Count;
-						} else if (op.type === "insert") {
-							// op.text is a JS string; use its UTF-16 length for cursor adjustment.
-							if (readPos <= selectionStart) {
-								newCursorStart += op.text.length;
-							}
-							if (readPos <= selectionEnd) {
-								newCursorEnd += op.text.length;
-							}
-							newValue += op.text;
-						} else {
-							// remove
-							// Convert atom count to UTF-16 units before adjusting cursors.
-							const utf16Count = utf16LengthForCodePoints(oldValue, readPos, op.count);
-							const removeEnd = readPos + utf16Count;
-							if (removeEnd <= selectionStart) {
-								newCursorStart -= utf16Count;
-							} else if (readPos < selectionStart) {
-								newCursorStart -= selectionStart - readPos;
-							}
-							if (removeEnd <= selectionEnd) {
-								newCursorEnd -= utf16Count;
-							} else if (readPos < selectionEnd) {
-								newCursorEnd -= selectionEnd - readPos;
-							}
-							readPos += utf16Count;
-						}
-					}
-
-					// Append any tail not covered by ops (e.g. trailing retained content).
-					newValue += oldValue.slice(readPos);
+					const result = applyTextOps(
+						textarea.value,
+						{ start: textarea.selectionStart, end: textarea.selectionEnd },
+						ops,
+					);
+					newValue = result.value;
+					newSelection = result.selection;
 				}
 				textarea.value = newValue;
 				// Keep the DOM's child text node in sync with `.value` so queries like
 				// `element.textContent` (used in tests / by external observers) reflect current
 				// content rather than the initial value baked in from `defaultValue`.
 				textarea.textContent = newValue;
-				if (newCursorStart !== undefined && newCursorEnd !== undefined) {
-					const clampedStart = Math.min(newCursorStart, newValue.length);
-					const clampedEnd = Math.min(newCursorEnd, newValue.length);
-					textarea.setSelectionRange(clampedStart, clampedEnd);
+				if (newSelection !== undefined) {
+					textarea.setSelectionRange(newSelection.start, newSelection.end);
 				}
 			} finally {
 				isUpdatingRef.current = false;
@@ -158,15 +111,7 @@ const PlainTextEditorView: FC<MainViewPropsInner> = ({ root, undoRedo, editLabel
 
 			isUpdatingRef.current = true;
 			try {
-				const newText = event.target.value;
-				const context = TreeAlpha.context(root);
-				if (context.isBranch()) {
-					context.runTransaction(() => syncTextToTree(root, newText), {
-						label: effectiveLabel,
-					});
-				} else {
-					syncTextToTree(root, newText);
-				}
+				applyTextEdit(root, event.target.value, effectiveLabel);
 			} finally {
 				isUpdatingRef.current = false;
 			}
diff --git a/packages/framework/react/src/text/plain/plainUtils.ts b/packages/framework/react/src/text/plain/plainUtils.ts
index 4b3aab48ca1e..3eb180ea4761 100644
--- a/packages/framework/react/src/text/plain/plainUtils.ts
+++ b/packages/framework/react/src/text/plain/plainUtils.ts
@@ -3,7 +3,163 @@
  * Licensed under the MIT License.
  */
 
-import type { TextAsTree } from "@fluidframework/tree/internal";
+import {
+	type TextAsTree,
+	TreeAlpha,
+	utf16LengthForCodePoints,
+} from "@fluidframework/tree/internal";
+
+/**
+ * A text selection or cursor range expressed as UTF-16 code-unit offsets.
+ * @remarks
+ * These match the `selectionStart` / `selectionEnd` properties of an HTML `<input>` / `<textarea>`,
+ * and the offsets used to index into a JavaScript string. A collapsed cursor has `start === end`.
+ * @internal
+ */
+export interface TextSelection {
+	/** UTF-16 offset of the start of the selection. */
+	readonly start: number;
+	/** UTF-16 offset of the end of the selection. */
+	readonly end: number;
+}
+
+/**
+ * The result of applying a character-level delta to an existing text value via {@link applyTextOps}.
+ * @internal
+ */
+export interface ApplyTextOpsResult {
+	/** The updated text value after applying the ops. */
+	readonly value: string;
+	/**
+	 * The input selection, adjusted to follow the same logical position across the edit.
+	 * @remarks
+	 * Always a valid range within {@link ApplyTextOpsResult.value} (each offset is clamped to
+	 * `[0, value.length]`), so it can be written straight back to an element without further bounds checks.
+	 */
+	readonly selection: TextSelection;
+}
+
+/**
+ * Apply a character-level delta to an existing text value, producing the new value and a
+ * selection range adjusted to track the same logical position across the edit.
+ * @remarks
+ * `ops` are the deltas delivered by {@link @fluidframework/tree#TextAsTree.Members.onCharactersChanged}.
+ * Applying them incrementally avoids a full O(N) re-read of the text on every change.
+ *
+ * This function is intentionally DOM-free so consumers maintaining their own UI (a custom React
+ * component, a non-`textarea` element, or a non-React renderer) can reuse it: read the current value
+ * and selection from your view, call this, then write the result back.
+ *
+ * `onCharactersChanged` delivers `undefined` (rather than an op list) when an incremental delta is
+ * unavailable; in that case skip this function and re-read the whole text via `root.fullString()`.
+ *
+ * Writing the result back must not re-enter the tree — see {@link applyTextEdit} for the re-entrancy pattern.
+ * @internal
+ */
+export function applyTextOps(
+	oldValue: string,
+	selection: TextSelection,
+	ops: readonly TextAsTree.TextOp[],
+): ApplyTextOpsResult {
+	const { start: selectionStart, end: selectionEnd } = selection;
+
+	// readPos is a UTF-16 code-unit index into oldValue.
+	let readPos = 0;
+	let value = "";
+	let newCursorStart = selectionStart;
+	let newCursorEnd = selectionEnd;
+
+	for (const op of ops) {
+		if (op.type === "retain") {
+			// Convert the code-point count to UTF-16 units by scanning the actual characters.
+			const utf16Count = utf16LengthForCodePoints(oldValue, readPos, op.count);
+			value += oldValue.slice(readPos, readPos + utf16Count);
+			readPos += utf16Count;
+		} else if (op.type === "insert") {
+			// op.text is a JS string; use its UTF-16 length for cursor adjustment.
+			if (readPos <= selectionStart) {
+				newCursorStart += op.text.length;
+			}
+			if (readPos <= selectionEnd) {
+				newCursorEnd += op.text.length;
+			}
+			value += op.text;
+		} else {
+			// remove
+			// Convert the code-point count to UTF-16 units before adjusting cursors.
+			const utf16Count = utf16LengthForCodePoints(oldValue, readPos, op.count);
+			const removeEnd = readPos + utf16Count;
+			if (removeEnd <= selectionStart) {
+				newCursorStart -= utf16Count;
+			} else if (readPos < selectionStart) {
+				newCursorStart -= selectionStart - readPos;
+			}
+			if (removeEnd <= selectionEnd) {
+				newCursorEnd -= utf16Count;
+			} else if (readPos < selectionEnd) {
+				newCursorEnd -= selectionEnd - readPos;
+			}
+			readPos += utf16Count;
+		}
+	}
+
+	// Append any tail not covered by ops (e.g. trailing retained content).
+	value += oldValue.slice(readPos);
+
+	// Clamp to a valid range within `value` so the result can be written back without further checks.
+	// A stale input selection (e.g. beyond `oldValue`) can otherwise land outside the new value.
+	const clamp = (offset: number): number => Math.min(Math.max(offset, 0), value.length);
+	return { value, selection: { start: clamp(newCursorStart), end: clamp(newCursorEnd) } };
+}
+
+/**
+ * Apply a user text edit to `root`, replacing its content with `newText`.
+ * @remarks
+ * When `root` belongs to a branch, the edit is wrapped in a transaction tagged with `label` so it
+ * can be independently undone/redone; otherwise the edit is applied directly.
+ *
+ * The diff and the underlying tree mutation are performed by {@link syncTextToTree}; this function
+ * only adds the branch-aware transaction wrapping on top. Call {@link syncTextToTree} directly if you
+ * want the mutation without a transaction.
+ *
+ * `label` defaults to `root` itself, giving each tree node its own independent undo/redo history.
+ *
+ * Mutating the tree synchronously fires
+ * {@link @fluidframework/tree#TextAsTree.Members.onCharactersChanged}. If you also subscribe to that
+ * event to apply remote edits to your view (e.g. via {@link applyTextOps}), set a re-entrancy flag
+ * before calling this and ignore the event while it is set — otherwise the edit you just made is
+ * echoed straight back onto your view. For example:
+ *
+ * ```typescript
+ * let updating = false;
+ * root.onCharactersChanged((ops) => {
+ *   if (updating) return; // ignore the echo of our own local edit
+ *   // ...apply ops to your view via applyTextOps...
+ * });
+ *
+ * function onUserInput(newText: string): void {
+ *   updating = true;
+ *   try {
+ *     applyTextEdit(root, newText);
+ *   } finally {
+ *     updating = false;
+ *   }
+ * }
+ * ```
+ * @internal
+ */
+export function applyTextEdit(
+	root: TextAsTree.Tree,
+	newText: string,
+	label: unknown = root,
+): void {
+	const context = TreeAlpha.context(root);
+	if (context.isBranch()) {
+		context.runTransaction(() => syncTextToTree(root, newText), { label });
+	} else {
+		syncTextToTree(root, newText);
+	}
+}
 
 /**
  * Sync `newText` into the provided `root` tree by applying the minimal remove + insert pair

From 9e526f335c0ebb867cf94ce38894019b106f0d91 Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Mon, 22 Jun 2026 23:05:19 +0000
Subject: [PATCH 02/10] add usePlainTextInput hook

---
 .../react/src/test/text/textEditor.test.tsx   |  90 ++++---
 .../framework/react/src/text/plain/index.ts   |   6 +
 .../react/src/text/plain/plainTextView.tsx    |  80 +-----
 .../react/src/text/plain/usePlainTextInput.ts | 246 ++++++++++++++++++
 4 files changed, 315 insertions(+), 107 deletions(-)
 create mode 100644 packages/framework/react/src/text/plain/usePlainTextInput.ts

diff --git a/packages/framework/react/src/test/text/textEditor.test.tsx b/packages/framework/react/src/test/text/textEditor.test.tsx
index eb4df620c69b..b5063a9a235b 100644
--- a/packages/framework/react/src/test/text/textEditor.test.tsx
+++ b/packages/framework/react/src/test/text/textEditor.test.tsx
@@ -6,13 +6,23 @@
 import { strict as assert } from "node:assert";
 
 import { TextAsTree } from "@fluidframework/tree/internal";
-import { render } from "@testing-library/react";
+import { act, render, renderHook } from "@testing-library/react";
 import globalJsdom from "global-jsdom";
+import type { ChangeEvent } from "react";
 
 import { toPropTreeNode } from "../../propNode.js";
 import { PlainTextMainView } from "../../text/index.js";
+// eslint-disable-next-line import-x/no-internal-modules -- the hook is not re-exported from text/index; import it directly for testing.
+import { usePlainTextInput } from "../../text/plain/usePlainTextInput.js";
 import type { UndoRedo } from "../../undoRedo.js";
 
+/** Read the current value of the editor's `<textarea>`. */
+function getTextareaValue(container: HTMLElement): string {
+	const textarea = container.querySelector("textarea");
+	assert.ok(textarea, "Textarea should be present");
+	return textarea.value;
+}
+
 describe("Plain TextArea view", () => {
 	let cleanup: () => void;
 	before(() => {
@@ -45,7 +55,7 @@ describe("Plain TextArea view", () => {
 					const content = <ViewComponent root={toPropTreeNode(text)} />;
 					const rendered = render(content, { reactStrictMode });
 
-					assert.match(rendered.baseElement.textContent ?? "", /Hello World/);
+					assert.equal(getTextareaValue(rendered.container), "Hello World");
 				});
 
 				it("invalidates view when tree is mutated", () => {
@@ -53,12 +63,10 @@ describe("Plain TextArea view", () => {
 					const content = <ViewComponent root={toPropTreeNode(text)} />;
 					const rendered = render(content, { reactStrictMode });
 
-					// Mutate the tree by inserting text
-					text.insertAt(5, " World");
+					// Mutate the tree by inserting text; the hook applies the delta to the textarea.
+					act(() => text.insertAt(5, " World"));
 
-					// Rerender and verify the view updates
-					rendered.rerender(content);
-					assert.match(rendered.baseElement.textContent ?? "", /Hello World/);
+					assert.equal(getTextareaValue(rendered.container), "Hello World");
 				});
 
 				it("invalidates view when text is removed", () => {
@@ -67,13 +75,9 @@ describe("Plain TextArea view", () => {
 					const rendered = render(content, { reactStrictMode });
 
 					// Mutate the tree by removing " World" (indices 5 to 11)
-					text.removeRange(5, 11);
+					act(() => text.removeRange(5, 11));
 
-					// Rerender and verify the view updates
-					rendered.rerender(content);
-					assert.match(rendered.baseElement.textContent ?? "", /Hello/);
-					assert(rendered.baseElement.textContent !== null);
-					assert.doesNotMatch(rendered.baseElement.textContent, /World/);
+					assert.equal(getTextareaValue(rendered.container), "Hello");
 				});
 
 				it("invalidates view when text is cleared and replaced", () => {
@@ -81,18 +85,15 @@ describe("Plain TextArea view", () => {
 					const content = <ViewComponent root={toPropTreeNode(text)} />;
 					const rendered = render(content, { reactStrictMode });
 
-					// Clear all text
-					const length = [...text.characters()].length;
-					text.removeRange(0, length);
-
-					// Insert new text
-					text.insertAt(0, "Replaced");
+					act(() => {
+						// Clear all text
+						const length = [...text.characters()].length;
+						text.removeRange(0, length);
+						// Insert new text
+						text.insertAt(0, "Replaced");
+					});
 
-					// Rerender and verify the view updates
-					rendered.rerender(content);
-					assert.match(rendered.baseElement.textContent ?? "", /Replaced/);
-					assert(rendered.baseElement.textContent !== null);
-					assert.doesNotMatch(rendered.baseElement.textContent, /Original/);
+					assert.equal(getTextareaValue(rendered.container), "Replaced");
 				});
 
 				// Tests for surrogate pair characters (emojis use 2 UTF-16 code units)
@@ -104,7 +105,7 @@ describe("Plain TextArea view", () => {
 					const content = <ViewComponent root={toPropTreeNode(text)} />;
 					const rendered = render(content, { reactStrictMode });
 
-					assert.match(rendered.baseElement.textContent ?? "", /Hello 😀 World/);
+					assert.equal(getTextareaValue(rendered.container), "Hello 😀 World");
 				});
 
 				it("inserts text after surrogate pair characters", () => {
@@ -113,10 +114,9 @@ describe("Plain TextArea view", () => {
 					const rendered = render(content, { reactStrictMode });
 
 					// Insert after the emoji (index 2 in character count: A, 😀, B)
-					text.insertAt(2, "X");
+					act(() => text.insertAt(2, "X"));
 
-					rendered.rerender(content);
-					assert.match(rendered.baseElement.textContent ?? "", /A😀XB/);
+					assert.equal(getTextareaValue(rendered.container), "A😀XB");
 				});
 
 				it("removes surrogate pair characters", () => {
@@ -125,12 +125,9 @@ describe("Plain TextArea view", () => {
 					const rendered = render(content, { reactStrictMode });
 
 					// Remove the emoji (index 1, length 1 in character count)
-					text.removeRange(1, 2);
+					act(() => text.removeRange(1, 2));
 
-					rendered.rerender(content);
-					assert.match(rendered.baseElement.textContent ?? "", /AB/);
-					assert(rendered.baseElement.textContent !== null);
-					assert.doesNotMatch(rendered.baseElement.textContent, /😀/);
+					assert.equal(getTextareaValue(rendered.container), "AB");
 				});
 
 				it("handles multiple surrogate pair characters", () => {
@@ -139,15 +136,36 @@ describe("Plain TextArea view", () => {
 					const rendered = render(content, { reactStrictMode });
 
 					// Insert between emojis
-					text.insertAt(2, "!");
+					act(() => text.insertAt(2, "!"));
 
-					rendered.rerender(content);
-					assert.match(rendered.baseElement.textContent ?? "", /👋🌍!🎉/);
+					assert.equal(getTextareaValue(rendered.container), "👋🌍!🎉");
 				});
+
 			});
 		}
 	});
 
+	// These drive the hook's handlers directly via renderHook. Simulating `onChange` through the
+	// DOM (fireEvent) does not trigger React's value-tracker in this jsdom/mocha harness, so the
+	// input → tree direction is exercised at the hook boundary.
+	describe("usePlainTextInput (input → tree)", () => {
+		// Minimal synthetic change event carrying only the field the handler reads.
+		function changeEvent(value: string): ChangeEvent<HTMLTextAreaElement> {
+			const event: unknown = { target: { value } };
+			return event as ChangeEvent<HTMLTextAreaElement>;
+		}
+
+		it("writes local edits back into the tree", () => {
+			const text = TextAsTree.Tree.fromString("Hello");
+			const { result } = renderHook(() => usePlainTextInput({ text }));
+
+			act(() => result.current.inputProps.onChange(changeEvent("Hello World")));
+
+			// The local edit reaches the tree (and its own echo is ignored, not re-applied).
+			assert.equal(text.fullString(), "Hello World");
+		});
+	});
+
 	describe("toolbar", () => {
 		const mockLabel = Symbol("test");
 		const mockUndoRedo: UndoRedo = {
diff --git a/packages/framework/react/src/text/plain/index.ts b/packages/framework/react/src/text/plain/index.ts
index 271d43a66ce2..12200101d0a0 100644
--- a/packages/framework/react/src/text/plain/index.ts
+++ b/packages/framework/react/src/text/plain/index.ts
@@ -14,3 +14,9 @@ export {
 	syncTextToTree,
 	type TextSelection,
 } from "./plainUtils.js";
+export {
+	usePlainTextInput,
+	type PlainTextInputBinding,
+	type PlainTextInputProps,
+	type UsePlainTextInputOptions,
+} from "./usePlainTextInput.js";
diff --git a/packages/framework/react/src/text/plain/plainTextView.tsx b/packages/framework/react/src/text/plain/plainTextView.tsx
index 68d926cae7e6..521fa24491b5 100644
--- a/packages/framework/react/src/text/plain/plainTextView.tsx
+++ b/packages/framework/react/src/text/plain/plainTextView.tsx
@@ -4,12 +4,12 @@
  */
 
 import type { TextAsTree } from "@fluidframework/tree/internal";
-import { type ChangeEvent, type FC, useCallback, useEffect, useReducer, useRef } from "react";
+import type { FC } from "react";
 
 import { unwrapPropTreeNode, type PropTreeNode } from "../../propNode.js";
 import type { TextEditorProps } from "../textEditorProps.js";
 
-import { applyTextEdit, applyTextOps, type TextSelection } from "./plainUtils.js";
+import { usePlainTextInput } from "./usePlainTextInput.js";
 
 /**
  * Props for the MainView component.
@@ -51,79 +51,19 @@ export const MainView: FC<MainViewProps> = ({ root, undoRedo, editLabel }) => {
  * remote changes to the textarea without a full re-read of the text.
  */
 const PlainTextEditorView: FC<MainViewPropsInner> = ({ root, undoRedo, editLabel }) => {
-	// Reference to the textarea element
-	const textareaRef = useRef<HTMLTextAreaElement>(null);
-	// Guards against update loops between textarea and the tree
-	const isUpdatingRef = useRef<boolean>(false);
-	// Force re-render when undo/redo state changes so button disabled state stays current.
-	const [, forceUpdate] = useReducer((x: number) => x + 1, 0);
+	// All input ↔ tree binding (subscription, re-entrancy guard, caret, change handler) lives in
+	// the hook. Passing `undoRedo` lets the hook re-render this component on each tree change so the
+	// undo/redo button disabled state stays current (it is otherwise re-render-free).
+	const { inputProps, focus } = usePlainTextInput({ text: root, editLabel, undoRedo });
 
-	// Effective label: explicit prop or the root node itself as the default.
+	// Effective label: explicit prop or the root node itself as the default (for the undo/redo buttons).
 	const effectiveLabel = editLabel ?? root;
 
-	// Subscribe to incremental tree changes and apply them to the textarea.
-	useEffect(() => {
-		return root.onCharactersChanged((ops) => {
-			if (isUpdatingRef.current || !textareaRef.current) {
-				return;
-			}
-
-			isUpdatingRef.current = true;
-			try {
-				const textarea = textareaRef.current;
-				let newValue: string;
-				let newSelection: TextSelection | undefined;
-				if (ops === undefined) {
-					// Delta unavailable — fall back to full re-read.
-					newValue = root.fullString();
-				} else {
-					// Apply ops incrementally to avoid a full O(N) re-read.
-					const result = applyTextOps(
-						textarea.value,
-						{ start: textarea.selectionStart, end: textarea.selectionEnd },
-						ops,
-					);
-					newValue = result.value;
-					newSelection = result.selection;
-				}
-				textarea.value = newValue;
-				// Keep the DOM's child text node in sync with `.value` so queries like
-				// `element.textContent` (used in tests / by external observers) reflect current
-				// content rather than the initial value baked in from `defaultValue`.
-				textarea.textContent = newValue;
-				if (newSelection !== undefined) {
-					textarea.setSelectionRange(newSelection.start, newSelection.end);
-				}
-			} finally {
-				isUpdatingRef.current = false;
-			}
-			// Refresh undo/redo button state — undo/redo availability changes alongside tree mutations.
-			if (undoRedo) forceUpdate();
-		});
-	}, [root, undoRedo]);
-
-	// Handle textarea changes - sync textarea → tree
-	const handleChange = useCallback(
-		(event: ChangeEvent<HTMLTextAreaElement>) => {
-			if (isUpdatingRef.current) {
-				return;
-			}
-
-			isUpdatingRef.current = true;
-			try {
-				applyTextEdit(root, event.target.value, effectiveLabel);
-			} finally {
-				isUpdatingRef.current = false;
-			}
-		},
-		[root, effectiveLabel],
-	);
-
 	return (
 		<div
 			className="text-editor-container"
 			style={{ height: "100%", display: "flex", flexDirection: "column" }}
-			onClick={() => textareaRef.current?.focus()}
+			onClick={focus}
 		>
 			<style>{`
 				.pt-toolbar {
@@ -171,9 +111,7 @@ const PlainTextEditorView: FC<MainViewPropsInner> = ({ root, undoRedo, editLabel
 				</div>
 			)}
 			<textarea
-				ref={textareaRef}
-				defaultValue={root.fullString()}
-				onChange={handleChange}
+				{...inputProps}
 				placeholder="Start typing..."
 				style={{
 					flex: 1,
diff --git a/packages/framework/react/src/text/plain/usePlainTextInput.ts b/packages/framework/react/src/text/plain/usePlainTextInput.ts
new file mode 100644
index 000000000000..b2d5e6dca2e8
--- /dev/null
+++ b/packages/framework/react/src/text/plain/usePlainTextInput.ts
@@ -0,0 +1,246 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { TextAsTree } from "@fluidframework/tree/internal";
+import {
+	type ChangeEventHandler,
+	type RefCallback,
+	useCallback,
+	useEffect,
+	useReducer,
+	useRef,
+	useState,
+} from "react";
+
+import type { UndoRedo } from "../../undoRedo.js";
+
+import { applyTextEdit, applyTextOps, type TextSelection } from "./plainUtils.js";
+
+/** An element this binding can drive: anything with `value` + selection APIs (`<input>`, `<textarea>`). */
+type TextInputElement = HTMLInputElement | HTMLTextAreaElement;
+
+/**
+ * Options for {@link usePlainTextInput}.
+ * @input @internal
+ */
+export interface UsePlainTextInputOptions {
+	/**
+	 * The plain-text tree node to bind to.
+	 * @remarks
+	 * May be `undefined` while the node is still being created/assigned; the binding attaches once
+	 * it becomes defined, and re-attaches if it is later swapped for a different node.
+	 */
+	readonly text: TextAsTree.Tree | undefined;
+
+	/**
+	 * Label used to tag edits made through this binding, so they can be undone/redone independently.
+	 * @remarks
+	 * Defaults to the {@link UsePlainTextInputOptions.text} node itself. Pass a stable per-editor
+	 * value (e.g. an editor id) to scope undo/redo to this editor instance. See {@link applyTextEdit}.
+	 */
+	readonly editLabel?: unknown;
+
+	/**
+	 * The function used to write a user edit back into the tree.
+	 * @remarks
+	 * Defaults to {@link applyTextEdit} (branch-aware, transaction-wrapped). Override it to supply a
+	 * custom transaction/label wrapper.
+	 */
+	readonly applyEdit?: (root: TextAsTree.Tree, newText: string, label: unknown) => void;
+
+	/**
+	 * Optional undo/redo manager.
+	 * @remarks
+	 * When provided, the hook re-renders the host component on each tree change so undo/redo
+	 * availability (e.g. button disabled state) stays current. Omit it to get zero re-renders on
+	 * both local and remote edits.
+	 */
+	readonly undoRedo?: UndoRedo;
+}
+
+/**
+ * Props produced by {@link usePlainTextInput} to spread onto an uncontrolled text input.
+ * @remarks
+ * Spread onto a native `<input>` / `<textarea>`:
+ *
+ * ```tsx
+ * const { inputProps } = usePlainTextInput({ text });
+ * return <textarea {...inputProps} />;
+ * ```
+ *
+ * For a component-library input that takes a slot ref (e.g. Fluent UI `<Input>`), apply the parts
+ * individually: `<Input defaultValue={inputProps.defaultValue} onChange={inputProps.onChange} input={{ ref: inputProps.ref }} />`.
+ * @internal
+ */
+export interface PlainTextInputProps {
+	/** Callback ref so the hook can read/write the element's value and selection. */
+	readonly ref: RefCallback<TextInputElement>;
+	/**
+	 * The element's initial content. The element is left **uncontrolled** — after mount the hook
+	 * keeps it in sync imperatively via incremental deltas, so typing does not trigger a re-render.
+	 */
+	readonly defaultValue: string;
+	/** Write local edits into the tree. */
+	readonly onChange: ChangeEventHandler<TextInputElement>;
+}
+
+/**
+ * The return value of {@link usePlainTextInput}.
+ * @internal
+ */
+export interface PlainTextInputBinding {
+	/** Spread onto an uncontrolled `<input>` / `<textarea>`. See {@link PlainTextInputProps}. */
+	readonly inputProps: PlainTextInputProps;
+	/** Focus the bound element (e.g. for a click-anywhere-to-focus container). */
+	readonly focus: () => void;
+}
+
+/**
+ * React hook that two-way binds an (uncontrolled) text input to a
+ * {@link @fluidframework/tree#TextAsTree.Tree}, returning spreadable input props.
+ * @remarks
+ * This is the headless convenience layer over the pure {@link applyTextOps} / {@link applyTextEdit}
+ * functions: it owns the glue that is easy to get wrong when wiring an editor by hand — subscribing
+ * to {@link @fluidframework/tree#TextAsTree.Members.onCharactersChanged} (and re-attaching when
+ * {@link UsePlainTextInputOptions.text} is lazily assigned or swapped), applying incremental remote
+ * deltas via {@link applyTextOps} (with a full re-read fallback) while preserving the caret, and a
+ * re-entrancy guard so a local edit's own echo is not re-applied.
+ *
+ * The element is left **uncontrolled** and updated imperatively, so typing does not trigger a React
+ * re-render. The hook works with any element exposing `value` + selection (`<input>`, `<textarea>`,
+ * or a component-library input via its slot ref).
+ *
+ * For non-`<input>` UIs (contenteditable, CodeMirror, canvas) or non-React renderers, use the pure
+ * {@link applyTextOps} / {@link applyTextEdit} functions directly.
+ *
+ * If you instead need a **controlled** input (React owns the value — e.g. it also feeds form state,
+ * validation, or a library input that does not forward a DOM ref), compose the same pure functions:
+ *
+ * ```tsx
+ * const updating = useRef(false);
+ * const [value, setValue] = useState(() => text.fullString());
+ * useEffect(
+ *   () =>
+ *     text.onCharactersChanged((ops) => {
+ *       if (updating.current) return; // ignore our own edit's echo
+ *       // Re-reads the whole string for brevity. To apply incrementally and preserve the caret,
+ *       // call applyTextOps(value, selection, ops) with the element's current selection and restore
+ *       // the returned selection in a useLayoutEffect (this hook does the imperative equivalent).
+ *       setValue(text.fullString());
+ *     }),
+ *   [text],
+ * );
+ * const onChange = (e) => {
+ *   setValue(e.target.value);
+ *   updating.current = true;
+ *   try {
+ *     applyTextEdit(text, e.target.value);
+ *   } finally {
+ *     updating.current = false;
+ *   }
+ * };
+ * // <input value={value} onChange={onChange} />
+ * ```
+ * @internal
+ */
+export function usePlainTextInput(options: UsePlainTextInputOptions): PlainTextInputBinding {
+	const { text, editLabel, applyEdit = applyTextEdit, undoRedo } = options;
+
+	// The bound element; needed to read/write its value and caret/selection.
+	const elementRef = useRef<TextInputElement | undefined>(undefined);
+	// Guards against re-applying the echo of our own local edit.
+	const isUpdatingRef = useRef<boolean>(false);
+	// Re-render trigger used only to refresh undo/redo button state (when `undoRedo` is provided).
+	const [, forceUpdate] = useReducer((x: number) => x + 1, 0);
+
+	// Effective label: explicit option or the text node itself as the default.
+	const effectiveLabel = editLabel ?? text;
+
+	// Computed once: an uncontrolled element only reads `defaultValue` at mount. Later content (and
+	// node swaps) are pushed into the element imperatively by the effect below.
+	const [defaultValue] = useState<string>(() => text?.fullString() ?? "");
+
+	// Tree → element: seed the element with the current node's content and subscribe to its changes.
+	// Re-runs when `text` is (re)assigned, so a lazily-populated or swapped node is picked up.
+	useEffect(() => {
+		if (text === undefined) {
+			return;
+		}
+
+		// Reflect the (possibly new) node's content into the uncontrolled element.
+		const seedElement = elementRef.current;
+		if (seedElement !== undefined) {
+			seedElement.value = text.fullString();
+		}
+
+		return text.onCharactersChanged((ops) => {
+			// Ignore the echo of our own local edit.
+			if (isUpdatingRef.current) {
+				return;
+			}
+			const element = elementRef.current;
+			if (element === undefined) {
+				return;
+			}
+
+			let newValue: string;
+			let newSelection: TextSelection | undefined;
+			if (ops === undefined) {
+				// Delta unavailable — fall back to a full re-read.
+				newValue = text.fullString();
+			} else {
+				// Apply ops incrementally to avoid a full O(N) re-read, adjusting the caret.
+				// `selectionStart`/`selectionEnd` are `number | null`; fall back to the end of the text.
+				const result = applyTextOps(
+					element.value,
+					{
+						start: element.selectionStart ?? element.value.length,
+						end: element.selectionEnd ?? element.value.length,
+					},
+					ops,
+				);
+				newValue = result.value;
+				newSelection = result.selection;
+			}
+			element.value = newValue;
+			if (newSelection !== undefined) {
+				element.setSelectionRange(newSelection.start, newSelection.end);
+			}
+			// Refresh undo/redo button state — only re-renders when an undo/redo manager is in use.
+			if (undoRedo) {
+				forceUpdate();
+			}
+		});
+	}, [text, undoRedo]);
+
+	// Element → tree: write the user's edit back into the tree (guarded against the resulting echo).
+	const onChange = useCallback<ChangeEventHandler<TextInputElement>>(
+		(event) => {
+			if (isUpdatingRef.current || text === undefined) {
+				return;
+			}
+			isUpdatingRef.current = true;
+			try {
+				applyEdit(text, event.target.value, effectiveLabel);
+			} finally {
+				isUpdatingRef.current = false;
+			}
+		},
+		[text, applyEdit, effectiveLabel],
+	);
+
+	const ref = useCallback<RefCallback<TextInputElement>>((element) => {
+		elementRef.current = element ?? undefined;
+	}, []);
+
+	const focus = useCallback((): void => {
+		elementRef.current?.focus();
+	}, []);
+
+	return {
+		inputProps: { ref, defaultValue, onChange },
+		focus,
+	};
+}

From 8faea4375e126a21efb3eb78f33147fc758b04fe Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Mon, 22 Jun 2026 23:17:06 +0000
Subject: [PATCH 03/10] undo redo bug fix

---
 .../react/src/test/text/textEditor.test.tsx   | 38 +++++++++++++++++++
 .../react/src/text/plain/plainTextView.tsx    |  5 +--
 .../react/src/text/plain/usePlainTextInput.ts | 16 ++++++--
 3 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/packages/framework/react/src/test/text/textEditor.test.tsx b/packages/framework/react/src/test/text/textEditor.test.tsx
index b5063a9a235b..29c09a99846d 100644
--- a/packages/framework/react/src/test/text/textEditor.test.tsx
+++ b/packages/framework/react/src/test/text/textEditor.test.tsx
@@ -164,6 +164,44 @@ describe("Plain TextArea view", () => {
 			// The local edit reaches the tree (and its own echo is ignored, not re-applied).
 			assert.equal(text.fullString(), "Hello World");
 		});
+
+		const noopUndoRedo: UndoRedo = {
+			undo: () => {},
+			redo: () => {},
+			canUndo: () => false,
+			canRedo: () => false,
+			dispose: () => {},
+		};
+
+		it("re-renders on a local edit when undoRedo is set, so button state refreshes", () => {
+			const text = TextAsTree.Tree.fromString("Hello");
+			let renders = 0;
+			const { result } = renderHook(() => {
+				renders++;
+				return usePlainTextInput({ text, undoRedo: noopUndoRedo });
+			});
+
+			const before = renders;
+			act(() => result.current.inputProps.onChange(changeEvent("Hello!")));
+
+			assert.equal(text.fullString(), "Hello!");
+			assert.ok(renders > before, "a local edit must re-render so undo/redo buttons refresh");
+		});
+
+		it("does not re-render on a local edit when undoRedo is omitted", () => {
+			const text = TextAsTree.Tree.fromString("Hello");
+			let renders = 0;
+			const { result } = renderHook(() => {
+				renders++;
+				return usePlainTextInput({ text });
+			});
+
+			const before = renders;
+			act(() => result.current.inputProps.onChange(changeEvent("Hello!")));
+
+			assert.equal(text.fullString(), "Hello!");
+			assert.equal(renders, before, "without undoRedo a local edit must not re-render");
+		});
 	});
 
 	describe("toolbar", () => {
diff --git a/packages/framework/react/src/text/plain/plainTextView.tsx b/packages/framework/react/src/text/plain/plainTextView.tsx
index 521fa24491b5..7f56fa28827b 100644
--- a/packages/framework/react/src/text/plain/plainTextView.tsx
+++ b/packages/framework/react/src/text/plain/plainTextView.tsx
@@ -51,9 +51,8 @@ export const MainView: FC<MainViewProps> = ({ root, undoRedo, editLabel }) => {
  * remote changes to the textarea without a full re-read of the text.
  */
 const PlainTextEditorView: FC<MainViewPropsInner> = ({ root, undoRedo, editLabel }) => {
-	// All input ↔ tree binding (subscription, re-entrancy guard, caret, change handler) lives in
-	// the hook. Passing `undoRedo` lets the hook re-render this component on each tree change so the
-	// undo/redo button disabled state stays current (it is otherwise re-render-free).
+	// All input ↔ tree binding lives in the hook; `undoRedo` is forwarded so it keeps the toolbar's
+	// enabled state in sync.
 	const { inputProps, focus } = usePlainTextInput({ text: root, editLabel, undoRedo });
 
 	// Effective label: explicit prop or the root node itself as the default (for the undo/redo buttons).
diff --git a/packages/framework/react/src/text/plain/usePlainTextInput.ts b/packages/framework/react/src/text/plain/usePlainTextInput.ts
index b2d5e6dca2e8..b8323338ac02 100644
--- a/packages/framework/react/src/text/plain/usePlainTextInput.ts
+++ b/packages/framework/react/src/text/plain/usePlainTextInput.ts
@@ -154,6 +154,10 @@ export function usePlainTextInput(options: UsePlainTextInputOptions): PlainTextI
 	const isUpdatingRef = useRef<boolean>(false);
 	// Re-render trigger used only to refresh undo/redo button state (when `undoRedo` is provided).
 	const [, forceUpdate] = useReducer((x: number) => x + 1, 0);
+	// Latest `undoRedo`, readable from event callbacks without making the subscription effect
+	// re-run (and re-seed the element) whenever `undoRedo` changes identity.
+	const undoRedoRef = useRef(undoRedo);
+	undoRedoRef.current = undoRedo;
 
 	// Effective label: explicit option or the text node itself as the default.
 	const effectiveLabel = editLabel ?? text;
@@ -169,7 +173,8 @@ export function usePlainTextInput(options: UsePlainTextInputOptions): PlainTextI
 			return;
 		}
 
-		// Reflect the (possibly new) node's content into the uncontrolled element.
+		// Reflect the (possibly new) node's content into the uncontrolled element. On a node swap
+		// the element briefly shows the previous node's value until this runs (one frame).
 		const seedElement = elementRef.current;
 		if (seedElement !== undefined) {
 			seedElement.value = text.fullString();
@@ -209,11 +214,11 @@ export function usePlainTextInput(options: UsePlainTextInputOptions): PlainTextI
 				element.setSelectionRange(newSelection.start, newSelection.end);
 			}
 			// Refresh undo/redo button state — only re-renders when an undo/redo manager is in use.
-			if (undoRedo) {
+			if (undoRedoRef.current !== undefined) {
 				forceUpdate();
 			}
 		});
-	}, [text, undoRedo]);
+	}, [text]);
 
 	// Element → tree: write the user's edit back into the tree (guarded against the resulting echo).
 	const onChange = useCallback<ChangeEventHandler<TextInputElement>>(
@@ -227,6 +232,11 @@ export function usePlainTextInput(options: UsePlainTextInputOptions): PlainTextI
 			} finally {
 				isUpdatingRef.current = false;
 			}
+			// Refresh undo/redo button state: this edit's own echo is skipped by the guard in the
+			// subscription, so a local edit's refresh has to happen here.
+			if (undoRedoRef.current !== undefined) {
+				forceUpdate();
+			}
 		},
 		[text, applyEdit, effectiveLabel],
 	);

From 88f03485b0d2f430744cbe6cd3d6761b20ef9d2f Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Mon, 22 Jun 2026 23:22:37 +0000
Subject: [PATCH 04/10] doc cleanup

---
 packages/framework/react/src/test/text/textEditor.test.tsx   | 2 --
 packages/framework/react/src/text/plain/usePlainTextInput.ts | 2 --
 2 files changed, 4 deletions(-)

diff --git a/packages/framework/react/src/test/text/textEditor.test.tsx b/packages/framework/react/src/test/text/textEditor.test.tsx
index 29c09a99846d..89fc4b98e69f 100644
--- a/packages/framework/react/src/test/text/textEditor.test.tsx
+++ b/packages/framework/react/src/test/text/textEditor.test.tsx
@@ -86,10 +86,8 @@ describe("Plain TextArea view", () => {
 					const rendered = render(content, { reactStrictMode });
 
 					act(() => {
-						// Clear all text
 						const length = [...text.characters()].length;
 						text.removeRange(0, length);
-						// Insert new text
 						text.insertAt(0, "Replaced");
 					});
 
diff --git a/packages/framework/react/src/text/plain/usePlainTextInput.ts b/packages/framework/react/src/text/plain/usePlainTextInput.ts
index b8323338ac02..197a8ed68eb2 100644
--- a/packages/framework/react/src/text/plain/usePlainTextInput.ts
+++ b/packages/framework/react/src/text/plain/usePlainTextInput.ts
@@ -159,7 +159,6 @@ export function usePlainTextInput(options: UsePlainTextInputOptions): PlainTextI
 	const undoRedoRef = useRef(undoRedo);
 	undoRedoRef.current = undoRedo;
 
-	// Effective label: explicit option or the text node itself as the default.
 	const effectiveLabel = editLabel ?? text;
 
 	// Computed once: an uncontrolled element only reads `defaultValue` at mount. Later content (and
@@ -181,7 +180,6 @@ export function usePlainTextInput(options: UsePlainTextInputOptions): PlainTextI
 		}
 
 		return text.onCharactersChanged((ops) => {
-			// Ignore the echo of our own local edit.
 			if (isUpdatingRef.current) {
 				return;
 			}

From b1ee35a35661d7b5550b804560f1f814c27f8d8f Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Tue, 23 Jun 2026 01:42:12 +0000
Subject: [PATCH 05/10] useTreeSynchronizedString hook for plain text

---
 .../react/src/test/text/textEditor.test.tsx   |  72 ++---
 .../framework/react/src/text/plain/index.ts   |   8 +-
 .../react/src/text/plain/plainTextView.tsx    |  50 +++-
 .../react/src/text/plain/usePlainTextInput.ts | 254 ------------------
 .../text/plain/useTreeSynchronizedString.ts   |  95 +++++++
 5 files changed, 159 insertions(+), 320 deletions(-)
 delete mode 100644 packages/framework/react/src/text/plain/usePlainTextInput.ts
 create mode 100644 packages/framework/react/src/text/plain/useTreeSynchronizedString.ts

diff --git a/packages/framework/react/src/test/text/textEditor.test.tsx b/packages/framework/react/src/test/text/textEditor.test.tsx
index 89fc4b98e69f..70a4c6c8d7e5 100644
--- a/packages/framework/react/src/test/text/textEditor.test.tsx
+++ b/packages/framework/react/src/test/text/textEditor.test.tsx
@@ -8,12 +8,11 @@ import { strict as assert } from "node:assert";
 import { TextAsTree } from "@fluidframework/tree/internal";
 import { act, render, renderHook } from "@testing-library/react";
 import globalJsdom from "global-jsdom";
-import type { ChangeEvent } from "react";
 
 import { toPropTreeNode } from "../../propNode.js";
 import { PlainTextMainView } from "../../text/index.js";
 // eslint-disable-next-line import-x/no-internal-modules -- the hook is not re-exported from text/index; import it directly for testing.
-import { usePlainTextInput } from "../../text/plain/usePlainTextInput.js";
+import { useTreeSynchronizedString } from "../../text/plain/useTreeSynchronizedString.js";
 import type { UndoRedo } from "../../undoRedo.js";
 
 /** Read the current value of the editor's `<textarea>`. */
@@ -63,7 +62,7 @@ describe("Plain TextArea view", () => {
 					const content = <ViewComponent root={toPropTreeNode(text)} />;
 					const rendered = render(content, { reactStrictMode });
 
-					// Mutate the tree by inserting text; the hook applies the delta to the textarea.
+					// Mutate the tree; the controlled textarea updates from the hook's synced text.
 					act(() => text.insertAt(5, " World"));
 
 					assert.equal(getTextareaValue(rendered.container), "Hello World");
@@ -143,62 +142,37 @@ describe("Plain TextArea view", () => {
 		}
 	});
 
-	// These drive the hook's handlers directly via renderHook. Simulating `onChange` through the
-	// DOM (fireEvent) does not trigger React's value-tracker in this jsdom/mocha harness, so the
-	// input → tree direction is exercised at the hook boundary.
-	describe("usePlainTextInput (input → tree)", () => {
-		// Minimal synthetic change event carrying only the field the handler reads.
-		function changeEvent(value: string): ChangeEvent<HTMLTextAreaElement> {
-			const event: unknown = { target: { value } };
-			return event as ChangeEvent<HTMLTextAreaElement>;
-		}
-
-		it("writes local edits back into the tree", () => {
+	// The hook is a one-way tree → string sync; exercise it directly via renderHook.
+	describe("useTreeSynchronizedString", () => {
+		it("returns the tree's current text", () => {
 			const text = TextAsTree.Tree.fromString("Hello");
-			const { result } = renderHook(() => usePlainTextInput({ text }));
+			const { result } = renderHook(() => useTreeSynchronizedString(text));
 
-			act(() => result.current.inputProps.onChange(changeEvent("Hello World")));
-
-			// The local edit reaches the tree (and its own echo is ignored, not re-applied).
-			assert.equal(text.fullString(), "Hello World");
+			assert.equal(result.current.text, "Hello");
 		});
 
-		const noopUndoRedo: UndoRedo = {
-			undo: () => {},
-			redo: () => {},
-			canUndo: () => false,
-			canRedo: () => false,
-			dispose: () => {},
-		};
-
-		it("re-renders on a local edit when undoRedo is set, so button state refreshes", () => {
+		it("syncs character changes into the returned text", () => {
 			const text = TextAsTree.Tree.fromString("Hello");
-			let renders = 0;
-			const { result } = renderHook(() => {
-				renders++;
-				return usePlainTextInput({ text, undoRedo: noopUndoRedo });
-			});
+			const { result } = renderHook(() => useTreeSynchronizedString(text));
 
-			const before = renders;
-			act(() => result.current.inputProps.onChange(changeEvent("Hello!")));
+			act(() => text.insertAt(5, " World"));
+			assert.equal(result.current.text, "Hello World");
 
-			assert.equal(text.fullString(), "Hello!");
-			assert.ok(renders > before, "a local edit must re-render so undo/redo buttons refresh");
+			act(() => text.removeRange(0, 6));
+			assert.equal(result.current.text, "World");
 		});
 
-		it("does not re-render on a local edit when undoRedo is omitted", () => {
+		it("adjusts the tracked selection across edits", () => {
 			const text = TextAsTree.Tree.fromString("Hello");
-			let renders = 0;
-			const { result } = renderHook(() => {
-				renders++;
-				return usePlainTextInput({ text });
-			});
-
-			const before = renders;
-			act(() => result.current.inputProps.onChange(changeEvent("Hello!")));
-
-			assert.equal(text.fullString(), "Hello!");
-			assert.equal(renders, before, "without undoRedo a local edit must not re-render");
+			// Caret after "Hello".
+			const { result } = renderHook(() =>
+				useTreeSynchronizedString(text, { start: 5, end: 5 }),
+			);
+
+			// Inserting before the caret shifts it right by the inserted length.
+			act(() => text.insertAt(0, "Oh "));
+			assert.equal(result.current.text, "Oh Hello");
+			assert.deepEqual(result.current.selection, { start: 8, end: 8 });
 		});
 	});
 
diff --git a/packages/framework/react/src/text/plain/index.ts b/packages/framework/react/src/text/plain/index.ts
index 12200101d0a0..c346eabdf52a 100644
--- a/packages/framework/react/src/text/plain/index.ts
+++ b/packages/framework/react/src/text/plain/index.ts
@@ -15,8 +15,6 @@ export {
 	type TextSelection,
 } from "./plainUtils.js";
 export {
-	usePlainTextInput,
-	type PlainTextInputBinding,
-	type PlainTextInputProps,
-	type UsePlainTextInputOptions,
-} from "./usePlainTextInput.js";
+	useTreeSynchronizedString,
+	type SynchronizedString,
+} from "./useTreeSynchronizedString.js";
diff --git a/packages/framework/react/src/text/plain/plainTextView.tsx b/packages/framework/react/src/text/plain/plainTextView.tsx
index 7f56fa28827b..24c63001eeab 100644
--- a/packages/framework/react/src/text/plain/plainTextView.tsx
+++ b/packages/framework/react/src/text/plain/plainTextView.tsx
@@ -4,12 +4,13 @@
  */
 
 import type { TextAsTree } from "@fluidframework/tree/internal";
-import type { FC } from "react";
+import { type ChangeEvent, type FC, useCallback, useLayoutEffect, useRef } from "react";
 
 import { unwrapPropTreeNode, type PropTreeNode } from "../../propNode.js";
 import type { TextEditorProps } from "../textEditorProps.js";
 
-import { usePlainTextInput } from "./usePlainTextInput.js";
+import { applyTextEdit } from "./plainUtils.js";
+import { useTreeSynchronizedString } from "./useTreeSynchronizedString.js";
 
 /**
  * Props for the MainView component.
@@ -46,23 +47,46 @@ export const MainView: FC<MainViewProps> = ({ root, undoRedo, editLabel }) => {
  * Uses TextAsTree for collaborative plain text storage.
  *
  * @remarks
- * Subscribes to incremental character-level deltas from the tree via
- * {@link @fluidframework/tree#TextAsTree.Members.onCharactersChanged} to apply
- * remote changes to the textarea without a full re-read of the text.
+ * A controlled textarea driven by {@link useTreeSynchronizedString} (tree → string); local edits
+ * are written back to the tree via {@link applyTextEdit} (string → tree). Doubles as a reference
+ * for binding a text input to a {@link @fluidframework/tree#TextAsTree.Tree}.
  */
 const PlainTextEditorView: FC<MainViewPropsInner> = ({ root, undoRedo, editLabel }) => {
-	// All input ↔ tree binding lives in the hook; `undoRedo` is forwarded so it keeps the toolbar's
-	// enabled state in sync.
-	const { inputProps, focus } = usePlainTextInput({ text: root, editLabel, undoRedo });
-
-	// Effective label: explicit prop or the root node itself as the default (for the undo/redo buttons).
 	const effectiveLabel = editLabel ?? root;
+	const textareaRef = useRef<HTMLTextAreaElement>(null);
+	// Distinguishes the local user's own edit (browser keeps the caret) from a remote one.
+	const isLocalEditRef = useRef<boolean>(false);
+
+	// Tree → string (one-way). The component supplies the other direction below.
+	const { text, selection } = useTreeSynchronizedString(root);
+
+	// A controlled value resets the caret on every change. For the user's own edit the browser
+	// already placed the caret correctly, so only restore the tracked selection for remote edits.
+	useLayoutEffect(() => {
+		if (isLocalEditRef.current) {
+			isLocalEditRef.current = false;
+			return;
+		}
+		const textarea = textareaRef.current;
+		if (textarea !== null && selection !== undefined) {
+			textarea.setSelectionRange(selection.start, selection.end);
+		}
+	}, [text, selection]);
+
+	// String → tree: write the user's edit back into the tree.
+	const onChange = useCallback(
+		(event: ChangeEvent<HTMLTextAreaElement>) => {
+			isLocalEditRef.current = true;
+			applyTextEdit(root, event.target.value, effectiveLabel);
+		},
+		[root, effectiveLabel],
+	);
 
 	return (
 		<div
 			className="text-editor-container"
 			style={{ height: "100%", display: "flex", flexDirection: "column" }}
-			onClick={focus}
+			onClick={() => textareaRef.current?.focus()}
 		>
 			<style>{`
 				.pt-toolbar {
@@ -110,7 +134,9 @@ const PlainTextEditorView: FC<MainViewPropsInner> = ({ root, undoRedo, editLabel
 				</div>
 			)}
 			<textarea
-				{...inputProps}
+				ref={textareaRef}
+				value={text}
+				onChange={onChange}
 				placeholder="Start typing..."
 				style={{
 					flex: 1,
diff --git a/packages/framework/react/src/text/plain/usePlainTextInput.ts b/packages/framework/react/src/text/plain/usePlainTextInput.ts
deleted file mode 100644
index 197a8ed68eb2..000000000000
--- a/packages/framework/react/src/text/plain/usePlainTextInput.ts
+++ /dev/null
@@ -1,254 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import type { TextAsTree } from "@fluidframework/tree/internal";
-import {
-	type ChangeEventHandler,
-	type RefCallback,
-	useCallback,
-	useEffect,
-	useReducer,
-	useRef,
-	useState,
-} from "react";
-
-import type { UndoRedo } from "../../undoRedo.js";
-
-import { applyTextEdit, applyTextOps, type TextSelection } from "./plainUtils.js";
-
-/** An element this binding can drive: anything with `value` + selection APIs (`<input>`, `<textarea>`). */
-type TextInputElement = HTMLInputElement | HTMLTextAreaElement;
-
-/**
- * Options for {@link usePlainTextInput}.
- * @input @internal
- */
-export interface UsePlainTextInputOptions {
-	/**
-	 * The plain-text tree node to bind to.
-	 * @remarks
-	 * May be `undefined` while the node is still being created/assigned; the binding attaches once
-	 * it becomes defined, and re-attaches if it is later swapped for a different node.
-	 */
-	readonly text: TextAsTree.Tree | undefined;
-
-	/**
-	 * Label used to tag edits made through this binding, so they can be undone/redone independently.
-	 * @remarks
-	 * Defaults to the {@link UsePlainTextInputOptions.text} node itself. Pass a stable per-editor
-	 * value (e.g. an editor id) to scope undo/redo to this editor instance. See {@link applyTextEdit}.
-	 */
-	readonly editLabel?: unknown;
-
-	/**
-	 * The function used to write a user edit back into the tree.
-	 * @remarks
-	 * Defaults to {@link applyTextEdit} (branch-aware, transaction-wrapped). Override it to supply a
-	 * custom transaction/label wrapper.
-	 */
-	readonly applyEdit?: (root: TextAsTree.Tree, newText: string, label: unknown) => void;
-
-	/**
-	 * Optional undo/redo manager.
-	 * @remarks
-	 * When provided, the hook re-renders the host component on each tree change so undo/redo
-	 * availability (e.g. button disabled state) stays current. Omit it to get zero re-renders on
-	 * both local and remote edits.
-	 */
-	readonly undoRedo?: UndoRedo;
-}
-
-/**
- * Props produced by {@link usePlainTextInput} to spread onto an uncontrolled text input.
- * @remarks
- * Spread onto a native `<input>` / `<textarea>`:
- *
- * ```tsx
- * const { inputProps } = usePlainTextInput({ text });
- * return <textarea {...inputProps} />;
- * ```
- *
- * For a component-library input that takes a slot ref (e.g. Fluent UI `<Input>`), apply the parts
- * individually: `<Input defaultValue={inputProps.defaultValue} onChange={inputProps.onChange} input={{ ref: inputProps.ref }} />`.
- * @internal
- */
-export interface PlainTextInputProps {
-	/** Callback ref so the hook can read/write the element's value and selection. */
-	readonly ref: RefCallback<TextInputElement>;
-	/**
-	 * The element's initial content. The element is left **uncontrolled** — after mount the hook
-	 * keeps it in sync imperatively via incremental deltas, so typing does not trigger a re-render.
-	 */
-	readonly defaultValue: string;
-	/** Write local edits into the tree. */
-	readonly onChange: ChangeEventHandler<TextInputElement>;
-}
-
-/**
- * The return value of {@link usePlainTextInput}.
- * @internal
- */
-export interface PlainTextInputBinding {
-	/** Spread onto an uncontrolled `<input>` / `<textarea>`. See {@link PlainTextInputProps}. */
-	readonly inputProps: PlainTextInputProps;
-	/** Focus the bound element (e.g. for a click-anywhere-to-focus container). */
-	readonly focus: () => void;
-}
-
-/**
- * React hook that two-way binds an (uncontrolled) text input to a
- * {@link @fluidframework/tree#TextAsTree.Tree}, returning spreadable input props.
- * @remarks
- * This is the headless convenience layer over the pure {@link applyTextOps} / {@link applyTextEdit}
- * functions: it owns the glue that is easy to get wrong when wiring an editor by hand — subscribing
- * to {@link @fluidframework/tree#TextAsTree.Members.onCharactersChanged} (and re-attaching when
- * {@link UsePlainTextInputOptions.text} is lazily assigned or swapped), applying incremental remote
- * deltas via {@link applyTextOps} (with a full re-read fallback) while preserving the caret, and a
- * re-entrancy guard so a local edit's own echo is not re-applied.
- *
- * The element is left **uncontrolled** and updated imperatively, so typing does not trigger a React
- * re-render. The hook works with any element exposing `value` + selection (`<input>`, `<textarea>`,
- * or a component-library input via its slot ref).
- *
- * For non-`<input>` UIs (contenteditable, CodeMirror, canvas) or non-React renderers, use the pure
- * {@link applyTextOps} / {@link applyTextEdit} functions directly.
- *
- * If you instead need a **controlled** input (React owns the value — e.g. it also feeds form state,
- * validation, or a library input that does not forward a DOM ref), compose the same pure functions:
- *
- * ```tsx
- * const updating = useRef(false);
- * const [value, setValue] = useState(() => text.fullString());
- * useEffect(
- *   () =>
- *     text.onCharactersChanged((ops) => {
- *       if (updating.current) return; // ignore our own edit's echo
- *       // Re-reads the whole string for brevity. To apply incrementally and preserve the caret,
- *       // call applyTextOps(value, selection, ops) with the element's current selection and restore
- *       // the returned selection in a useLayoutEffect (this hook does the imperative equivalent).
- *       setValue(text.fullString());
- *     }),
- *   [text],
- * );
- * const onChange = (e) => {
- *   setValue(e.target.value);
- *   updating.current = true;
- *   try {
- *     applyTextEdit(text, e.target.value);
- *   } finally {
- *     updating.current = false;
- *   }
- * };
- * // <input value={value} onChange={onChange} />
- * ```
- * @internal
- */
-export function usePlainTextInput(options: UsePlainTextInputOptions): PlainTextInputBinding {
-	const { text, editLabel, applyEdit = applyTextEdit, undoRedo } = options;
-
-	// The bound element; needed to read/write its value and caret/selection.
-	const elementRef = useRef<TextInputElement | undefined>(undefined);
-	// Guards against re-applying the echo of our own local edit.
-	const isUpdatingRef = useRef<boolean>(false);
-	// Re-render trigger used only to refresh undo/redo button state (when `undoRedo` is provided).
-	const [, forceUpdate] = useReducer((x: number) => x + 1, 0);
-	// Latest `undoRedo`, readable from event callbacks without making the subscription effect
-	// re-run (and re-seed the element) whenever `undoRedo` changes identity.
-	const undoRedoRef = useRef(undoRedo);
-	undoRedoRef.current = undoRedo;
-
-	const effectiveLabel = editLabel ?? text;
-
-	// Computed once: an uncontrolled element only reads `defaultValue` at mount. Later content (and
-	// node swaps) are pushed into the element imperatively by the effect below.
-	const [defaultValue] = useState<string>(() => text?.fullString() ?? "");
-
-	// Tree → element: seed the element with the current node's content and subscribe to its changes.
-	// Re-runs when `text` is (re)assigned, so a lazily-populated or swapped node is picked up.
-	useEffect(() => {
-		if (text === undefined) {
-			return;
-		}
-
-		// Reflect the (possibly new) node's content into the uncontrolled element. On a node swap
-		// the element briefly shows the previous node's value until this runs (one frame).
-		const seedElement = elementRef.current;
-		if (seedElement !== undefined) {
-			seedElement.value = text.fullString();
-		}
-
-		return text.onCharactersChanged((ops) => {
-			if (isUpdatingRef.current) {
-				return;
-			}
-			const element = elementRef.current;
-			if (element === undefined) {
-				return;
-			}
-
-			let newValue: string;
-			let newSelection: TextSelection | undefined;
-			if (ops === undefined) {
-				// Delta unavailable — fall back to a full re-read.
-				newValue = text.fullString();
-			} else {
-				// Apply ops incrementally to avoid a full O(N) re-read, adjusting the caret.
-				// `selectionStart`/`selectionEnd` are `number | null`; fall back to the end of the text.
-				const result = applyTextOps(
-					element.value,
-					{
-						start: element.selectionStart ?? element.value.length,
-						end: element.selectionEnd ?? element.value.length,
-					},
-					ops,
-				);
-				newValue = result.value;
-				newSelection = result.selection;
-			}
-			element.value = newValue;
-			if (newSelection !== undefined) {
-				element.setSelectionRange(newSelection.start, newSelection.end);
-			}
-			// Refresh undo/redo button state — only re-renders when an undo/redo manager is in use.
-			if (undoRedoRef.current !== undefined) {
-				forceUpdate();
-			}
-		});
-	}, [text]);
-
-	// Element → tree: write the user's edit back into the tree (guarded against the resulting echo).
-	const onChange = useCallback<ChangeEventHandler<TextInputElement>>(
-		(event) => {
-			if (isUpdatingRef.current || text === undefined) {
-				return;
-			}
-			isUpdatingRef.current = true;
-			try {
-				applyEdit(text, event.target.value, effectiveLabel);
-			} finally {
-				isUpdatingRef.current = false;
-			}
-			// Refresh undo/redo button state: this edit's own echo is skipped by the guard in the
-			// subscription, so a local edit's refresh has to happen here.
-			if (undoRedoRef.current !== undefined) {
-				forceUpdate();
-			}
-		},
-		[text, applyEdit, effectiveLabel],
-	);
-
-	const ref = useCallback<RefCallback<TextInputElement>>((element) => {
-		elementRef.current = element ?? undefined;
-	}, []);
-
-	const focus = useCallback((): void => {
-		elementRef.current?.focus();
-	}, []);
-
-	return {
-		inputProps: { ref, defaultValue, onChange },
-		focus,
-	};
-}
diff --git a/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts b/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
new file mode 100644
index 000000000000..def4755cff41
--- /dev/null
+++ b/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
@@ -0,0 +1,95 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { TextAsTree } from "@fluidframework/tree/internal";
+import { useEffect, useRef, useState } from "react";
+
+import { applyTextOps, type TextSelection } from "./plainUtils.js";
+
+/**
+ * The value returned by {@link useTreeSynchronizedString}.
+ * @internal
+ */
+export interface SynchronizedString {
+	/** The tree's current text. */
+	readonly text: string;
+	/**
+	 * A selection range tracked across edits.
+	 * @remarks
+	 * Seeded from `initialSelection` and adjusted by {@link applyTextOps} as the text changes. It
+	 * follows the same logical position across edits, but the hook does not observe the user's live
+	 * caret, so a consumer that needs an accurate caret should track the element's selection itself.
+	 */
+	readonly selection: TextSelection | undefined;
+}
+
+/**
+ * React hook that provides a one-way sync from a {@link @fluidframework/tree#TextAsTree.Tree} to a
+ * string: it returns the tree's current text (and a tracked selection), recomputed whenever the
+ * tree's characters change.
+ * @remarks
+ * This is the small, broadly-applicable primitive for reading a text tree in React. It owns only the
+ * subscription and the incremental {@link applyTextOps} apply (with a full re-read fallback). It
+ * makes no assumption about how the string is rendered (`<input>`, `<textarea>`, contenteditable,
+ * canvas, …) and intentionally does **not** handle writing back to the tree.
+ *
+ * The consumer supplies the other direction (string → tree) themselves, typically by calling
+ * {@link applyTextEdit} from their input's change handler:
+ *
+ * ```tsx
+ * const { text } = useTreeSynchronizedString(tree);
+ * return (
+ *   <textarea
+ *     value={text}
+ *     onChange={(e) => applyTextEdit(tree, e.target.value)}
+ *   />
+ * );
+ * ```
+ * @internal
+ */
+export function useTreeSynchronizedString(
+	tree: TextAsTree.Tree,
+	initialSelection?: TextSelection,
+): SynchronizedString {
+	const [text, setText] = useState<string>(() => tree.fullString());
+	const [selection, setSelection] = useState<TextSelection | undefined>(initialSelection);
+
+	// Mirror the latest text/selection in refs so the change listener reads current values without
+	// having to re-subscribe (which would re-run the effect) on every update.
+	const textRef = useRef(text);
+	textRef.current = text;
+	const selectionRef = useRef(selection);
+	selectionRef.current = selection;
+
+	useEffect(() => {
+		// Re-seed when the bound node changes.
+		const full = tree.fullString();
+		textRef.current = full;
+		setText(full);
+
+		return tree.onCharactersChanged((ops) => {
+			if (ops === undefined) {
+				// No incremental delta available — re-read the whole string (selection unchanged).
+				const reread = tree.fullString();
+				textRef.current = reread;
+				setText(reread);
+				return;
+			}
+
+			const oldText = textRef.current;
+			const oldSelection = selectionRef.current ?? {
+				start: oldText.length,
+				end: oldText.length,
+			};
+			const result = applyTextOps(oldText, oldSelection, ops);
+			textRef.current = result.value;
+			selectionRef.current = result.selection;
+			setText(result.value);
+			setSelection(result.selection);
+		});
+	}, [tree]);
+
+	return { text, selection };
+}

From 9c33b7974009188ad62c99a6f93ec905de0bafa8 Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Thu, 2 Jul 2026 15:40:01 +0000
Subject: [PATCH 06/10] lint fix

---
 packages/framework/react/src/test/text/textEditor.test.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/framework/react/src/test/text/textEditor.test.tsx b/packages/framework/react/src/test/text/textEditor.test.tsx
index 70a4c6c8d7e5..1ad89d3b7d70 100644
--- a/packages/framework/react/src/test/text/textEditor.test.tsx
+++ b/packages/framework/react/src/test/text/textEditor.test.tsx
@@ -137,7 +137,6 @@ describe("Plain TextArea view", () => {
 
 					assert.equal(getTextareaValue(rendered.container), "👋🌍!🎉");
 				});
-
 			});
 		}
 	});

From 51c248536a139c44aa62d1b9c0bf382895f9c615 Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Mon, 6 Jul 2026 16:56:49 +0000
Subject: [PATCH 07/10] PR review

---
 .../react/src/test/text/plainUtils.test.ts    |  2 +-
 .../react/src/test/text/textEditor.test.tsx   | 12 +++++
 .../framework/react/src/text/plain/index.ts   |  2 -
 .../react/src/text/plain/plainUtils.ts        | 18 +++----
 .../text/plain/useTreeSynchronizedString.ts   | 52 ++++++++++++-------
 5 files changed, 54 insertions(+), 32 deletions(-)

diff --git a/packages/framework/react/src/test/text/plainUtils.test.ts b/packages/framework/react/src/test/text/plainUtils.test.ts
index 5057e267c642..b1d35ceb67f4 100644
--- a/packages/framework/react/src/test/text/plainUtils.test.ts
+++ b/packages/framework/react/src/test/text/plainUtils.test.ts
@@ -77,7 +77,7 @@ describe("plainUtils", () => {
 			return view;
 		}
 
-		it("applies the edit directly to an unhydrated (non-branch) node", () => {
+		it("applies the edit to an unhydrated (non-branch) node", () => {
 			const root = TextAsTree.Tree.fromString("hello");
 			applyTextEdit(root, "hello world");
 			assert.equal(root.fullString(), "hello world");
diff --git a/packages/framework/react/src/test/text/textEditor.test.tsx b/packages/framework/react/src/test/text/textEditor.test.tsx
index 1ad89d3b7d70..3e5fe3a0d847 100644
--- a/packages/framework/react/src/test/text/textEditor.test.tsx
+++ b/packages/framework/react/src/test/text/textEditor.test.tsx
@@ -173,6 +173,18 @@ describe("Plain TextArea view", () => {
 			assert.equal(result.current.text, "Oh Hello");
 			assert.deepEqual(result.current.selection, { start: 8, end: 8 });
 		});
+
+		it("leaves the selection undefined when none was provided", () => {
+			const text = TextAsTree.Tree.fromString("Hello");
+			const { result } = renderHook(() => useTreeSynchronizedString(text));
+
+			assert.equal(result.current.selection, undefined);
+
+			// The text still syncs, but no selection is fabricated after an edit.
+			act(() => text.insertAt(5, " World"));
+			assert.equal(result.current.text, "Hello World");
+			assert.equal(result.current.selection, undefined);
+		});
 	});
 
 	describe("toolbar", () => {
diff --git a/packages/framework/react/src/text/plain/index.ts b/packages/framework/react/src/text/plain/index.ts
index c346eabdf52a..7180ac79b56d 100644
--- a/packages/framework/react/src/text/plain/index.ts
+++ b/packages/framework/react/src/text/plain/index.ts
@@ -9,8 +9,6 @@ export {
 } from "./plainTextView.js";
 export {
 	applyTextEdit,
-	applyTextOps,
-	type ApplyTextOpsResult,
 	syncTextToTree,
 	type TextSelection,
 } from "./plainUtils.js";
diff --git a/packages/framework/react/src/text/plain/plainUtils.ts b/packages/framework/react/src/text/plain/plainUtils.ts
index 3eb180ea4761..0c34e2ddbba7 100644
--- a/packages/framework/react/src/text/plain/plainUtils.ts
+++ b/packages/framework/react/src/text/plain/plainUtils.ts
@@ -115,12 +115,13 @@ export function applyTextOps(
 /**
  * Apply a user text edit to `root`, replacing its content with `newText`.
  * @remarks
- * When `root` belongs to a branch, the edit is wrapped in a transaction tagged with `label` so it
- * can be independently undone/redone; otherwise the edit is applied directly.
+ * The edit is wrapped in a single transaction tagged with `label`, so the remove + insert pair it
+ * produces is applied atomically and can be reverted as a unit. When `root` belongs to a branch, the
+ * `label` is surfaced in that branch's change metadata for undo/redo grouping.
  *
  * The diff and the underlying tree mutation are performed by {@link syncTextToTree}; this function
- * only adds the branch-aware transaction wrapping on top. Call {@link syncTextToTree} directly if you
- * want the mutation without a transaction.
+ * only adds the transaction wrapping on top. Call {@link syncTextToTree} directly if you want the
+ * mutation without a transaction.
  *
  * `label` defaults to `root` itself, giving each tree node its own independent undo/redo history.
  *
@@ -153,12 +154,9 @@ export function applyTextEdit(
 	newText: string,
 	label: unknown = root,
 ): void {
-	const context = TreeAlpha.context(root);
-	if (context.isBranch()) {
-		context.runTransaction(() => syncTextToTree(root, newText), { label });
-	} else {
-		syncTextToTree(root, newText);
-	}
+	// `runTransaction` is callable on any context (a branch or an unhydrated node), so no branch check
+	// is needed here; the `label` is used for undo/redo grouping where the context supports it.
+	TreeAlpha.context(root).runTransaction(() => syncTextToTree(root, newText), { label });
 }
 
 /**
diff --git a/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts b/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
index def4755cff41..93579d5bb9cf 100644
--- a/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
+++ b/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
@@ -16,11 +16,13 @@ export interface SynchronizedString {
 	/** The tree's current text. */
 	readonly text: string;
 	/**
-	 * A selection range tracked across edits.
+	 * A selection range tracked across edits, or `undefined` when no selection is being tracked.
 	 * @remarks
-	 * Seeded from `initialSelection` and adjusted by {@link applyTextOps} as the text changes. It
-	 * follows the same logical position across edits, but the hook does not observe the user's live
-	 * caret, so a consumer that needs an accurate caret should track the element's selection itself.
+	 * Seeded from the `initialSelection` passed to {@link useTreeSynchronizedString} and adjusted by
+	 * {@link applyTextOps} so it follows the same logical position as the text changes.
+	 *
+	 * This is not a live caret: the hook does not observe the user's actual cursor, so a consumer that
+	 * needs the real caret position must read it from the rendered element itself.
 	 */
 	readonly selection: TextSelection | undefined;
 }
@@ -30,13 +32,14 @@ export interface SynchronizedString {
  * string: it returns the tree's current text (and a tracked selection), recomputed whenever the
  * tree's characters change.
  * @remarks
- * This is the small, broadly-applicable primitive for reading a text tree in React. It owns only the
- * subscription and the incremental {@link applyTextOps} apply (with a full re-read fallback). It
- * makes no assumption about how the string is rendered (`<input>`, `<textarea>`, contenteditable,
+ * This makes no assumption about how the string is rendered (`<input>`, `<textarea>`, contenteditable,
  * canvas, …) and intentionally does **not** handle writing back to the tree.
  *
- * The consumer supplies the other direction (string → tree) themselves, typically by calling
- * {@link applyTextEdit} from their input's change handler:
+ * The consumer supplies the other direction (string → tree) themselves. Different text APIs report
+ * their edits in different formats, so there is no one-size-fits-all mapping; prefer translating the
+ * API's own change delta into an incremental tree edit whenever it exposes one. For simple APIs like
+ * `<textarea>`, whose change events only surface the fully-updated string, {@link applyTextEdit}
+ * provides a naive diff-and-apply that is sufficient:
  *
  * ```tsx
  * const { text } = useTreeSynchronizedString(tree);
@@ -64,30 +67,41 @@ export function useTreeSynchronizedString(
 	selectionRef.current = selection;
 
 	useEffect(() => {
-		// Re-seed when the bound node changes.
 		const full = tree.fullString();
 		textRef.current = full;
 		setText(full);
 
 		return tree.onCharactersChanged((ops) => {
 			if (ops === undefined) {
-				// No incremental delta available — re-read the whole string (selection unchanged).
+				// A delta could not be computed (e.g. during a schema upgrade, or when the tree is out
+				// of sync with the delta), so re-read the whole string. Any tracked selection is clamped
+				// into the new text, since a shrinking edit could otherwise leave it out of bounds.
 				const reread = tree.fullString();
 				textRef.current = reread;
 				setText(reread);
+				if (selectionRef.current !== undefined) {
+					const clamp = (offset: number): number =>
+						Math.min(Math.max(offset, 0), reread.length);
+					const clamped = {
+						start: clamp(selectionRef.current.start),
+						end: clamp(selectionRef.current.end),
+					};
+					selectionRef.current = clamped;
+					setSelection(clamped);
+				}
 				return;
 			}
 
-			const oldText = textRef.current;
-			const oldSelection = selectionRef.current ?? {
-				start: oldText.length,
-				end: oldText.length,
-			};
-			const result = applyTextOps(oldText, oldSelection, ops);
+			// Only track a selection if the consumer supplied one; otherwise leave it undefined and
+			// discard the range returned by applyTextOps.
+			const oldSelection = selectionRef.current;
+			const result = applyTextOps(textRef.current, oldSelection ?? { start: 0, end: 0 }, ops);
 			textRef.current = result.value;
-			selectionRef.current = result.selection;
 			setText(result.value);
-			setSelection(result.selection);
+			if (oldSelection !== undefined) {
+				selectionRef.current = result.selection;
+				setSelection(result.selection);
+			}
 		});
 	}, [tree]);
 

From bc15e83a013dcecef66aaf999da4b0e6309d6adf Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Mon, 6 Jul 2026 17:13:32 +0000
Subject: [PATCH 08/10] Comment fix

---
 .../react/src/text/plain/useTreeSynchronizedString.ts    | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts b/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
index 93579d5bb9cf..454144ab8402 100644
--- a/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
+++ b/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
@@ -73,9 +73,12 @@ export function useTreeSynchronizedString(
 
 		return tree.onCharactersChanged((ops) => {
 			if (ops === undefined) {
-				// A delta could not be computed (e.g. during a schema upgrade, or when the tree is out
-				// of sync with the delta), so re-read the whole string. Any tracked selection is clamped
-				// into the new text, since a shrinking edit could otherwise leave it out of bounds.
+				// No incremental delta is available for this change, so re-read the whole string.
+				// This happens when the character field's marks couldn't be composed into a single
+				// delta — e.g. the field was modified across multiple batches within one flush (such
+				// as an interleaved schema change) — or when the tree is out of sync with the delta.
+				// Any tracked selection is clamped into the new text, since a shrinking edit could
+				// otherwise leave it out of bounds.
 				const reread = tree.fullString();
 				textRef.current = reread;
 				setText(reread);

From ac5856ebfd191f8dfcaf56738f603b97abd9a61e Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Wed, 8 Jul 2026 17:44:37 +0000
Subject: [PATCH 09/10] PR review

---
 .../react/src/test/text/plainUtils.test.ts    | 104 +++++++++++++----
 .../react/src/test/text/textEditor.test.tsx   |  50 +--------
 .../text/useTreeSynchronizedString.spec.ts    | 106 ++++++++++++++++++
 .../framework/react/src/text/plain/index.ts   |   1 -
 .../react/src/text/plain/plainTextView.tsx    |  14 ++-
 .../react/src/text/plain/plainUtils.ts        |  82 ++++++++------
 .../text/plain/useTreeSynchronizedString.ts   |  32 +++---
 packages/framework/react/src/utilities.ts     |   8 ++
 8 files changed, 269 insertions(+), 128 deletions(-)
 create mode 100644 packages/framework/react/src/test/text/useTreeSynchronizedString.spec.ts

diff --git a/packages/framework/react/src/test/text/plainUtils.test.ts b/packages/framework/react/src/test/text/plainUtils.test.ts
index b1d35ceb67f4..10e66b1a6a96 100644
--- a/packages/framework/react/src/test/text/plainUtils.test.ts
+++ b/packages/framework/react/src/test/text/plainUtils.test.ts
@@ -5,7 +5,7 @@
 
 import { strict as assert } from "node:assert";
 
-import { TextAsTree } from "@fluidframework/tree/internal";
+import { TextAsTree, TreeAlpha } from "@fluidframework/tree/internal";
 import {
 	independentView,
 	TreeViewConfiguration,
@@ -13,9 +13,14 @@ import {
 } from "@fluidframework/tree/alpha";
 
 import { createUndoRedo } from "../../undoRedo.js";
-// Allow import of file being tested
-// eslint-disable-next-line import-x/no-internal-modules
-import { applyTextEdit, applyTextOps, computeSync } from "../../text/plain/plainUtils.js";
+/* eslint-disable import-x/no-internal-modules -- Allow import of the file being tested. */
+import {
+	applyTextOps,
+	collapseSelectionOnReread,
+	computeSync,
+	syncTextToTree,
+} from "../../text/plain/plainUtils.js";
+/* eslint-enable import-x/no-internal-modules */
 
 describe("plainUtils", () => {
 	describe("applyTextOps", () => {
@@ -68,49 +73,100 @@ describe("plainUtils", () => {
 			]);
 			assert.deepEqual(result, { value: "lo", selection: { start: 2, end: 2 } });
 		});
+
+		it("collapses a selection to a caret when its whole range is removed", () => {
+			// "abcdef" with selection "cd" (2-4); remove "bcde" (1-5), which fully contains the selection.
+			// Both offsets pull back to the removal start, leaving a collapsed caret.
+			const result = applyTextOps("abcdef", { start: 2, end: 4 }, [
+				{ type: "retain", count: 1 },
+				{ type: "remove", count: 4 },
+				{ type: "retain", count: 1 },
+			]);
+			assert.deepEqual(result, { value: "af", selection: { start: 1, end: 1 } });
+		});
+
+		it("leaves a selection unchanged when the edit is entirely after it", () => {
+			// "abcdef" with selection "a" (0-1); remove "de" (3-5), which is past the selection.
+			const result = applyTextOps("abcdef", { start: 0, end: 1 }, [
+				{ type: "retain", count: 3 },
+				{ type: "remove", count: 2 },
+				{ type: "retain", count: 1 },
+			]);
+			assert.deepEqual(result, { value: "abcf", selection: { start: 0, end: 1 } });
+		});
+
+		it("shifts a collapsed caret right when text is inserted before it", () => {
+			// "ab" with a collapsed caret at the end (2); insert "XYZ" at the caret.
+			const result = applyTextOps("ab", { start: 2, end: 2 }, [
+				{ type: "retain", count: 2 },
+				{ type: "insert", text: "XYZ" },
+			]);
+			assert.deepEqual(result, { value: "abXYZ", selection: { start: 5, end: 5 } });
+		});
+	});
+
+	describe("collapseSelectionOnReread", () => {
+		it("returns undefined when no selection is tracked", () => {
+			assert.equal(collapseSelectionOnReread(undefined, 5), undefined);
+		});
+
+		it("collapses a range to a caret at its start, rather than preserving the range", () => {
+			// The whole point of the policy: a range must NOT survive the reread as a range, even when
+			// both offsets still fit in the new text (which is where independent clamping went wrong).
+			assert.deepEqual(collapseSelectionOnReread({ start: 0, end: 5 }, 7), {
+				start: 0,
+				end: 0,
+			});
+		});
+
+		it("clamps the caret into the new (shorter) text", () => {
+			assert.deepEqual(collapseSelectionOnReread({ start: 10, end: 12 }, 3), {
+				start: 3,
+				end: 3,
+			});
+		});
+
+		it("keeps an already-collapsed caret in place when still in range", () => {
+			assert.deepEqual(collapseSelectionOnReread({ start: 2, end: 2 }, 5), {
+				start: 2,
+				end: 2,
+			});
+		});
 	});
 
-	describe("applyTextEdit", () => {
+	describe("syncTextToTree", () => {
 		function createTextView(initial: string): TreeViewAlpha<typeof TextAsTree.Tree> {
 			const view = independentView(new TreeViewConfiguration({ schema: TextAsTree.Tree }));
 			view.initialize(TextAsTree.Tree.fromString(initial));
 			return view;
 		}
 
-		it("applies the edit to an unhydrated (non-branch) node", () => {
+		it("replaces the tree's content with the new text", () => {
 			const root = TextAsTree.Tree.fromString("hello");
-			applyTextEdit(root, "hello world");
+			syncTextToTree(root, "hello world");
 			assert.equal(root.fullString(), "hello world");
 		});
 
-		it("wraps the edit in a transaction tagged with the given label when on a branch", () => {
+		it("is atomically undoable when wrapped in a labeled transaction", () => {
 			const view = createTextView("hello");
 			const label = Symbol("editor");
 			const manager = createUndoRedo(view);
 
-			applyTextEdit(view.root, "hello world", label);
+			// The reference pattern used by callers: wrap the sync in a labeled transaction so the
+			// remove + insert pair is reverted together in a single undo step.
+			TreeAlpha.context(view.root).runTransaction(
+				() => syncTextToTree(view.root, "hello world"),
+				{
+					label,
+				},
+			);
 			assert.equal(view.root.fullString(), "hello world");
 
-			// The edit was a single transaction tagged with `label`, so a label-scoped undo
-			// reverts the whole edit in one step.
 			assert(manager.canUndo(label));
 			manager.undo(label);
 			assert.equal(view.root.fullString(), "hello");
 			manager.dispose();
 		});
-
-		it("defaults the transaction label to the root node when none is given", () => {
-			const view = createTextView("hello");
-			const manager = createUndoRedo(view);
-
-			applyTextEdit(view.root, "hello world");
-
-			// With no explicit label, the edit is tagged with `root` itself.
-			assert(manager.canUndo(view.root));
-			manager.undo(view.root);
-			assert.equal(view.root.fullString(), "hello");
-			manager.dispose();
-		});
 	});
 
 	describe("computeSync", () => {
diff --git a/packages/framework/react/src/test/text/textEditor.test.tsx b/packages/framework/react/src/test/text/textEditor.test.tsx
index 3e5fe3a0d847..53cf5ade0655 100644
--- a/packages/framework/react/src/test/text/textEditor.test.tsx
+++ b/packages/framework/react/src/test/text/textEditor.test.tsx
@@ -6,13 +6,11 @@
 import { strict as assert } from "node:assert";
 
 import { TextAsTree } from "@fluidframework/tree/internal";
-import { act, render, renderHook } from "@testing-library/react";
+import { act, render } from "@testing-library/react";
 import globalJsdom from "global-jsdom";
 
 import { toPropTreeNode } from "../../propNode.js";
 import { PlainTextMainView } from "../../text/index.js";
-// eslint-disable-next-line import-x/no-internal-modules -- the hook is not re-exported from text/index; import it directly for testing.
-import { useTreeSynchronizedString } from "../../text/plain/useTreeSynchronizedString.js";
 import type { UndoRedo } from "../../undoRedo.js";
 
 /** Read the current value of the editor's `<textarea>`. */
@@ -141,52 +139,6 @@ describe("Plain TextArea view", () => {
 		}
 	});
 
-	// The hook is a one-way tree → string sync; exercise it directly via renderHook.
-	describe("useTreeSynchronizedString", () => {
-		it("returns the tree's current text", () => {
-			const text = TextAsTree.Tree.fromString("Hello");
-			const { result } = renderHook(() => useTreeSynchronizedString(text));
-
-			assert.equal(result.current.text, "Hello");
-		});
-
-		it("syncs character changes into the returned text", () => {
-			const text = TextAsTree.Tree.fromString("Hello");
-			const { result } = renderHook(() => useTreeSynchronizedString(text));
-
-			act(() => text.insertAt(5, " World"));
-			assert.equal(result.current.text, "Hello World");
-
-			act(() => text.removeRange(0, 6));
-			assert.equal(result.current.text, "World");
-		});
-
-		it("adjusts the tracked selection across edits", () => {
-			const text = TextAsTree.Tree.fromString("Hello");
-			// Caret after "Hello".
-			const { result } = renderHook(() =>
-				useTreeSynchronizedString(text, { start: 5, end: 5 }),
-			);
-
-			// Inserting before the caret shifts it right by the inserted length.
-			act(() => text.insertAt(0, "Oh "));
-			assert.equal(result.current.text, "Oh Hello");
-			assert.deepEqual(result.current.selection, { start: 8, end: 8 });
-		});
-
-		it("leaves the selection undefined when none was provided", () => {
-			const text = TextAsTree.Tree.fromString("Hello");
-			const { result } = renderHook(() => useTreeSynchronizedString(text));
-
-			assert.equal(result.current.selection, undefined);
-
-			// The text still syncs, but no selection is fabricated after an edit.
-			act(() => text.insertAt(5, " World"));
-			assert.equal(result.current.text, "Hello World");
-			assert.equal(result.current.selection, undefined);
-		});
-	});
-
 	describe("toolbar", () => {
 		const mockLabel = Symbol("test");
 		const mockUndoRedo: UndoRedo = {
diff --git a/packages/framework/react/src/test/text/useTreeSynchronizedString.spec.ts b/packages/framework/react/src/test/text/useTreeSynchronizedString.spec.ts
new file mode 100644
index 000000000000..20a77d8fae2a
--- /dev/null
+++ b/packages/framework/react/src/test/text/useTreeSynchronizedString.spec.ts
@@ -0,0 +1,106 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { strict as assert } from "node:assert";
+
+import { TextAsTree } from "@fluidframework/tree/internal";
+import { act, renderHook } from "@testing-library/react";
+import globalJsdom from "global-jsdom";
+
+// Allow import of the file being tested; the hook is not re-exported from text/index.
+// eslint-disable-next-line import-x/no-internal-modules
+import { useTreeSynchronizedString } from "../../text/plain/useTreeSynchronizedString.js";
+
+describe("useTreeSynchronizedString", () => {
+	let cleanup: () => void;
+	before(() => {
+		cleanup = globalJsdom();
+	});
+	after(() => {
+		cleanup();
+	});
+
+	it("returns the tree's current text", () => {
+		const text = TextAsTree.Tree.fromString("Hello");
+		const { result } = renderHook(() => useTreeSynchronizedString(text));
+
+		assert.equal(result.current.text, "Hello");
+	});
+
+	it("syncs character changes into the returned text", () => {
+		const text = TextAsTree.Tree.fromString("Hello");
+		const { result } = renderHook(() => useTreeSynchronizedString(text));
+
+		act(() => text.insertAt(5, " World"));
+		assert.equal(result.current.text, "Hello World");
+
+		act(() => text.removeRange(0, 6));
+		assert.equal(result.current.text, "World");
+	});
+
+	it("re-seeds the text when a different tree is bound", () => {
+		const treeA = TextAsTree.Tree.fromString("A");
+		const treeB = TextAsTree.Tree.fromString("B");
+		const { result, rerender } = renderHook(({ tree }) => useTreeSynchronizedString(tree), {
+			initialProps: { tree: treeA },
+		});
+		assert.equal(result.current.text, "A");
+
+		rerender({ tree: treeB });
+		assert.equal(result.current.text, "B");
+	});
+
+	describe("selection", () => {
+		it("adjusts the tracked selection across edits", () => {
+			const text = TextAsTree.Tree.fromString("Hello");
+			// Caret after "Hello".
+			const { result } = renderHook(() =>
+				useTreeSynchronizedString(text, { start: 5, end: 5 }),
+			);
+
+			// Inserting before the caret shifts it right by the inserted length.
+			act(() => text.insertAt(0, "Oh "));
+			assert.equal(result.current.text, "Oh Hello");
+			assert.deepEqual(result.current.selection, { start: 8, end: 8 });
+		});
+
+		it("collapses the selection to a caret when its range is deleted", () => {
+			const text = TextAsTree.Tree.fromString("Hello");
+			// Select the whole word.
+			const { result } = renderHook(() =>
+				useTreeSynchronizedString(text, { start: 0, end: 5 }),
+			);
+
+			act(() => text.removeRange(0, 5));
+			assert.equal(result.current.text, "");
+			assert.deepEqual(result.current.selection, { start: 0, end: 0 });
+		});
+
+		it("pulls the selection back within bounds after a shrinking edit", () => {
+			const text = TextAsTree.Tree.fromString("Hello World");
+			// Select "World".
+			const { result } = renderHook(() =>
+				useTreeSynchronizedString(text, { start: 6, end: 11 }),
+			);
+
+			// Delete everything; the selection must not point past the new (empty) text.
+			act(() => text.removeRange(0, 11));
+			assert.equal(result.current.text, "");
+			assert.deepEqual(result.current.selection, { start: 0, end: 0 });
+		});
+
+		it("leaves the selection undefined when none was provided", () => {
+			const text = TextAsTree.Tree.fromString("Hello");
+			const { result } = renderHook(() => useTreeSynchronizedString(text));
+
+			assert.equal(result.current.selection, undefined);
+
+			// The text still syncs, but no selection is fabricated after an edit.
+			act(() => text.insertAt(5, " World"));
+			assert.equal(result.current.text, "Hello World");
+			assert.equal(result.current.selection, undefined);
+		});
+	});
+});
diff --git a/packages/framework/react/src/text/plain/index.ts b/packages/framework/react/src/text/plain/index.ts
index 7180ac79b56d..a61052a49f92 100644
--- a/packages/framework/react/src/text/plain/index.ts
+++ b/packages/framework/react/src/text/plain/index.ts
@@ -8,7 +8,6 @@ export {
 	type MainViewProps as PlainTextMainViewProps,
 } from "./plainTextView.js";
 export {
-	applyTextEdit,
 	syncTextToTree,
 	type TextSelection,
 } from "./plainUtils.js";
diff --git a/packages/framework/react/src/text/plain/plainTextView.tsx b/packages/framework/react/src/text/plain/plainTextView.tsx
index 24c63001eeab..24cfad0f219e 100644
--- a/packages/framework/react/src/text/plain/plainTextView.tsx
+++ b/packages/framework/react/src/text/plain/plainTextView.tsx
@@ -3,13 +3,13 @@
  * Licensed under the MIT License.
  */
 
-import type { TextAsTree } from "@fluidframework/tree/internal";
+import { TreeAlpha, type TextAsTree } from "@fluidframework/tree/internal";
 import { type ChangeEvent, type FC, useCallback, useLayoutEffect, useRef } from "react";
 
 import { unwrapPropTreeNode, type PropTreeNode } from "../../propNode.js";
 import type { TextEditorProps } from "../textEditorProps.js";
 
-import { applyTextEdit } from "./plainUtils.js";
+import { syncTextToTree } from "./plainUtils.js";
 import { useTreeSynchronizedString } from "./useTreeSynchronizedString.js";
 
 /**
@@ -48,7 +48,8 @@ export const MainView: FC<MainViewProps> = ({ root, undoRedo, editLabel }) => {
  *
  * @remarks
  * A controlled textarea driven by {@link useTreeSynchronizedString} (tree → string); local edits
- * are written back to the tree via {@link applyTextEdit} (string → tree). Doubles as a reference
+ * are written back to the tree via {@link syncTextToTree}, wrapped in a transaction so each edit is
+ * atomically undoable/redoable (string → tree). Doubles as a reference
  * for binding a text input to a {@link @fluidframework/tree#TextAsTree.Tree}.
  */
 const PlainTextEditorView: FC<MainViewPropsInner> = ({ root, undoRedo, editLabel }) => {
@@ -73,11 +74,14 @@ const PlainTextEditorView: FC<MainViewPropsInner> = ({ root, undoRedo, editLabel
 		}
 	}, [text, selection]);
 
-	// String → tree: write the user's edit back into the tree.
+	// String → tree: write the user's edit back into the tree, wrapped in a transaction tagged with
+	// `effectiveLabel` so the remove + insert pair is applied atomically and undone/redone as a unit.
 	const onChange = useCallback(
 		(event: ChangeEvent<HTMLTextAreaElement>) => {
 			isLocalEditRef.current = true;
-			applyTextEdit(root, event.target.value, effectiveLabel);
+			TreeAlpha.context(root).runTransaction(() => syncTextToTree(root, event.target.value), {
+				label: effectiveLabel,
+			});
 		},
 		[root, effectiveLabel],
 	);
diff --git a/packages/framework/react/src/text/plain/plainUtils.ts b/packages/framework/react/src/text/plain/plainUtils.ts
index 0c34e2ddbba7..0e4a0ba73aa1 100644
--- a/packages/framework/react/src/text/plain/plainUtils.ts
+++ b/packages/framework/react/src/text/plain/plainUtils.ts
@@ -3,11 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import {
-	type TextAsTree,
-	TreeAlpha,
-	utf16LengthForCodePoints,
-} from "@fluidframework/tree/internal";
+import { type TextAsTree, utf16LengthForCodePoints } from "@fluidframework/tree/internal";
+
+import { clamp } from "../../utilities.js";
 
 /**
  * A text selection or cursor range expressed as UTF-16 code-unit offsets.
@@ -53,7 +51,7 @@ export interface ApplyTextOpsResult {
  * `onCharactersChanged` delivers `undefined` (rather than an op list) when an incremental delta is
  * unavailable; in that case skip this function and re-read the whole text via `root.fullString()`.
  *
- * Writing the result back must not re-enter the tree — see {@link applyTextEdit} for the re-entrancy pattern.
+ * Writing the result back must not re-enter the tree — see {@link syncTextToTree} for the re-entrancy pattern.
  * @internal
  */
 export function applyTextOps(
@@ -108,22 +106,54 @@ export function applyTextOps(
 
 	// Clamp to a valid range within `value` so the result can be written back without further checks.
 	// A stale input selection (e.g. beyond `oldValue`) can otherwise land outside the new value.
-	const clamp = (offset: number): number => Math.min(Math.max(offset, 0), value.length);
-	return { value, selection: { start: clamp(newCursorStart), end: clamp(newCursorEnd) } };
+	return {
+		value,
+		selection: {
+			start: clamp(newCursorStart, 0, value.length),
+			end: clamp(newCursorEnd, 0, value.length),
+		},
+	};
 }
 
 /**
- * Apply a user text edit to `root`, replacing its content with `newText`.
+ * Collapse a tracked selection to a single caret, for use when a text change arrives without an
+ * incremental delta and the whole string must be re-read.
  * @remarks
- * The edit is wrapped in a single transaction tagged with `label`, so the remove + insert pair it
- * produces is applied atomically and can be reverted as a unit. When `root` belongs to a branch, the
- * `label` is surfaced in that branch's change metadata for undo/redo grouping.
+ * When no delta is available (see {@link @fluidframework/tree#TextAsTree.Members.onCharactersChanged}),
+ * there is no reliable way to map a selection *range* across the edit: preserving `start`/`end`
+ * independently can leave a range spanning characters unrelated to the original selection (e.g. when a
+ * batch deletes the selected text and inserts new text of similar length). To avoid presenting a
+ * misleading highlight, the range is collapsed to a caret at the (clamped) previous `start` offset,
+ * which keeps the caret near its prior position in the common benign case while never selecting
+ * unrelated characters.
  *
- * The diff and the underlying tree mutation are performed by {@link syncTextToTree}; this function
- * only adds the transaction wrapping on top. Call {@link syncTextToTree} directly if you want the
- * mutation without a transaction.
+ * Returns `undefined` when `selection` is `undefined`, so an untracked selection stays untracked.
+ * @param selection - The selection to collapse, or `undefined` if none is tracked.
+ * @param length - The length of the re-read text; the caret is clamped to `[0, length]`.
+ * @internal
+ */
+export function collapseSelectionOnReread(
+	selection: TextSelection | undefined,
+	length: number,
+): TextSelection | undefined {
+	if (selection === undefined) {
+		return undefined;
+	}
+	const caret = clamp(selection.start, 0, length);
+	return { start: caret, end: caret };
+}
+
+/**
+ * Sync `newText` into the provided `root` tree by applying the minimal remove + insert pair
+ * needed to transform the tree's current content into `newText`.
+ * @remarks
+ * The diff is computed by finding the longest shared prefix/suffix between current and new content
+ * and replacing only the middle span.
  *
- * `label` defaults to `root` itself, giving each tree node its own independent undo/redo history.
+ * To make the edit atomically undoable/redoable, wrap this call in a transaction, e.g.
+ * `TreeAlpha.context(root).runTransaction(() => syncTextToTree(root, newText), { label })`. The
+ * `label` correlates the edit for undo/redo grouping where the context supports it (see
+ * {@link @fluidframework/tree#TreeContextAlpha.runTransaction}).
  *
  * Mutating the tree synchronously fires
  * {@link @fluidframework/tree#TextAsTree.Members.onCharactersChanged}. If you also subscribe to that
@@ -141,7 +171,7 @@ export function applyTextOps(
  * function onUserInput(newText: string): void {
  *   updating = true;
  *   try {
- *     applyTextEdit(root, newText);
+ *     syncTextToTree(root, newText);
  *   } finally {
  *     updating = false;
  *   }
@@ -149,24 +179,6 @@ export function applyTextOps(
  * ```
  * @internal
  */
-export function applyTextEdit(
-	root: TextAsTree.Tree,
-	newText: string,
-	label: unknown = root,
-): void {
-	// `runTransaction` is callable on any context (a branch or an unhydrated node), so no branch check
-	// is needed here; the `label` is used for undo/redo grouping where the context supports it.
-	TreeAlpha.context(root).runTransaction(() => syncTextToTree(root, newText), { label });
-}
-
-/**
- * Sync `newText` into the provided `root` tree by applying the minimal remove + insert pair
- * needed to transform the tree's current content into `newText`.
- * @remarks
- * The diff is computed by finding the longest shared prefix/suffix between current and new content
- * and replacing only the middle span.
- * @internal
- */
 export function syncTextToTree(root: TextAsTree.Tree, newText: string): void {
 	const sync = computeSync(root.charactersCopy(), [...newText]);
 
diff --git a/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts b/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
index 454144ab8402..28464b99ea07 100644
--- a/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
+++ b/packages/framework/react/src/text/plain/useTreeSynchronizedString.ts
@@ -6,7 +6,7 @@
 import type { TextAsTree } from "@fluidframework/tree/internal";
 import { useEffect, useRef, useState } from "react";
 
-import { applyTextOps, type TextSelection } from "./plainUtils.js";
+import { applyTextOps, collapseSelectionOnReread, type TextSelection } from "./plainUtils.js";
 
 /**
  * The value returned by {@link useTreeSynchronizedString}.
@@ -21,6 +21,10 @@ export interface SynchronizedString {
 	 * Seeded from the `initialSelection` passed to {@link useTreeSynchronizedString} and adjusted by
 	 * {@link applyTextOps} so it follows the same logical position as the text changes.
 	 *
+	 * When an incremental delta is unavailable and the hook must re-read the whole string, the range
+	 * cannot be faithfully mapped across the edit, so it is collapsed to a single caret at the
+	 * (clamped) previous start offset.
+	 *
 	 * This is not a live caret: the hook does not observe the user's actual cursor, so a consumer that
 	 * needs the real caret position must read it from the rendered element itself.
 	 */
@@ -38,15 +42,18 @@ export interface SynchronizedString {
  * The consumer supplies the other direction (string → tree) themselves. Different text APIs report
  * their edits in different formats, so there is no one-size-fits-all mapping; prefer translating the
  * API's own change delta into an incremental tree edit whenever it exposes one. For simple APIs like
- * `<textarea>`, whose change events only surface the fully-updated string, {@link applyTextEdit}
- * provides a naive diff-and-apply that is sufficient:
+ * `<textarea>`, whose change events only surface the fully-updated string, {@link syncTextToTree}
+ * provides a naive diff-and-apply that is sufficient (wrap it in a transaction to make the edit
+ * atomically undoable):
  *
  * ```tsx
  * const { text } = useTreeSynchronizedString(tree);
  * return (
  *   <textarea
  *     value={text}
- *     onChange={(e) => applyTextEdit(tree, e.target.value)}
+ *     onChange={(e) =>
+ *       TreeAlpha.context(tree).runTransaction(() => syncTextToTree(tree, e.target.value))
+ *     }
  *   />
  * );
  * ```
@@ -77,20 +84,17 @@ export function useTreeSynchronizedString(
 				// This happens when the character field's marks couldn't be composed into a single
 				// delta — e.g. the field was modified across multiple batches within one flush (such
 				// as an interleaved schema change) — or when the tree is out of sync with the delta.
-				// Any tracked selection is clamped into the new text, since a shrinking edit could
-				// otherwise leave it out of bounds.
 				const reread = tree.fullString();
 				textRef.current = reread;
 				setText(reread);
+				// Without a delta we can't know how the text mutated, so we can't faithfully move a
+				// selection range across the edit. Collapse it to a caret rather than leave a range
+				// spanning what may now be unrelated characters — see collapseSelectionOnReread. A
+				// consumer that needs an accurate caret should read it from the rendered element.
 				if (selectionRef.current !== undefined) {
-					const clamp = (offset: number): number =>
-						Math.min(Math.max(offset, 0), reread.length);
-					const clamped = {
-						start: clamp(selectionRef.current.start),
-						end: clamp(selectionRef.current.end),
-					};
-					selectionRef.current = clamped;
-					setSelection(clamped);
+					const collapsed = collapseSelectionOnReread(selectionRef.current, reread.length);
+					selectionRef.current = collapsed;
+					setSelection(collapsed);
 				}
 				return;
 			}
diff --git a/packages/framework/react/src/utilities.ts b/packages/framework/react/src/utilities.ts
index 346a15c2d71b..e393fbf7224d 100644
--- a/packages/framework/react/src/utilities.ts
+++ b/packages/framework/react/src/utilities.ts
@@ -40,3 +40,11 @@ export function areSetsDisjoint(a: ReadonlySet<unknown>, b: ReadonlySet<unknown>
 	}
 	return true;
 }
+
+/**
+ * Clamps `value` to the inclusive range [`min`, `max`].
+ * @remarks Assumes `min <= max`.
+ */
+export function clamp(value: number, min: number, max: number): number {
+	return Math.min(Math.max(value, min), max);
+}

From 5ad7af2afbef90830119b740affda97260b874f9 Mon Sep 17 00:00:00 2001
From: daesunp <138815173+daesunp@users.noreply.github.com>
Date: Wed, 8 Jul 2026 20:58:57 +0000
Subject: [PATCH 10/10] doc fix

---
 packages/framework/react/src/text/plain/plainUtils.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/framework/react/src/text/plain/plainUtils.ts b/packages/framework/react/src/text/plain/plainUtils.ts
index 0e4a0ba73aa1..1f1ebced61fb 100644
--- a/packages/framework/react/src/text/plain/plainUtils.ts
+++ b/packages/framework/react/src/text/plain/plainUtils.ts
@@ -157,7 +157,7 @@ export function collapseSelectionOnReread(
  *
  * Mutating the tree synchronously fires
  * {@link @fluidframework/tree#TextAsTree.Members.onCharactersChanged}. If you also subscribe to that
- * event to apply remote edits to your view (e.g. via {@link applyTextOps}), set a re-entrancy flag
+ * event to apply remote edits to your view (e.g. via `applyTextOps`), set a re-entrancy flag
  * before calling this and ignore the event while it is set — otherwise the edit you just made is
  * echoed straight back onto your view. For example:
  *