@fluidframework/tree 2.92.0 → 2.93.0

package/src/simple-tree/api/treeAlpha.ts

@@ -5,14 +5,17 @@
 
 import type { NodeKind, TreeNode, WithType } from "../core/index.js";
 
+import type { TreeChangeEventsBeta } from "./treeBeta.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
+import type { ArrayNodeDeltaOp, ArrayNodeTreeChangedDeltaOp } from "./treeNodeApi.js";
 export type {
 	ArrayNodeDeltaOp,
 	ArrayNodeInsertOp,
 	ArrayNodeRemoveOp,
 	ArrayNodeRetainOp,
+	ArrayNodeTreeChangedDeltaOp,
+	ArrayNodeTreeChangedRetainOp,
 } from "./treeNodeApi.js";
-import type { ArrayNodeDeltaOp } from "./treeNodeApi.js";
 
 /**
  * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an object, map, or record node.
@@ -35,18 +38,16 @@ export interface NodeChangedDataProperties<TNode extends TreeNode = TreeNode> {
 }
 
 /**
- * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an array node.
+ * Data carried by the {@link TreeChangeEventsAlpha.nodeChanged} event for array nodes.
  * @sealed @alpha
  */
 export interface NodeChangedDataDelta {
 	/**
 	 * The sequential operations describing what changed in the array node.
 	 * @remarks
-	 * The value may be `undefined` in two cases:
-	 * - The node was created locally and has not yet been inserted into a document tree (a known
-	 * temporary limitation, tracked in AB#63261).
-	 * - The document was updated in a way that required multiple internal change passes in a single
-	 * operation (for example, a data change combined with a schema upgrade).
+	 * The value may be `undefined` when the document was updated in a way that required multiple
+	 * internal change passes in a single operation (for example, a data change combined with a
+	 * schema upgrade).
 	 *
 	 * See {@link ArrayNodeDeltaOp} for op semantics.
 	 */
@@ -54,7 +55,30 @@ export interface NodeChangedDataDelta {
 }
 
 /**
- * The data passed to {@link TreeChangeEventsAlpha.nodeChanged}.
+ * Data carried by the {@link TreeChangeEventsAlpha.treeChanged} event for array nodes.
+ * @remarks
+ * Extends {@link NodeChangedDataDelta}: the retain ops in the delta additionally carry a
+ * {@link ArrayNodeTreeChangedRetainOp.subtreeChanged} flag indicating whether any descendant
+ * of the retained element changed.
+ * @sealed @alpha
+ */
+export interface NodeChangedDataTreeDelta {
+	/**
+	 * The sequential operations describing what changed in the array node,
+	 * including subtree-change information on retain ops.
+	 * @remarks
+	 * The value may be `undefined` when the document was updated in a way that required multiple
+	 * internal change passes in a single operation (for example, a data change combined with a
+	 * schema upgrade).
+	 *
+	 * See {@link ArrayNodeTreeChangedDeltaOp} for op semantics.
+	 */
+	readonly delta: readonly ArrayNodeTreeChangedDeltaOp[] | undefined;
+}
+
+/**
+ * The data passed to {@link TreeChangeEventsAlpha.nodeChanged} and, for array nodes,
+ * to {@link TreeChangeEventsAlpha.treeChanged}.
  * @remarks
  * - For array nodes: {@link NodeChangedDataDelta} (includes a {@link NodeChangedDataDelta.delta | delta} payload).
  * - For object, map, and record nodes: {@link NodeChangedDataProperties} (includes {@link NodeChangedDataProperties.changedProperties | changedProperties}).
@@ -69,22 +93,61 @@ export type NodeChangedDataAlpha<TNode extends TreeNode = TreeNode> =
 			: NodeChangedDataProperties<TNode> | NodeChangedDataDelta;
 
 /**
- * Extension of {@link TreeChangeEvents} with a richer `nodeChanged` event.
+ * Extension of {@link TreeChangeEvents} with a richer `nodeChanged` event and a
+ * delta-carrying `treeChanged` event for array nodes.
  * @remarks
  * Provides a `nodeChanged` event that includes a delta payload for array nodes and
  * requires `changedProperties` for object, map, and record nodes.
+ * Also provides a `treeChanged` event that, for array nodes, carries a {@link NodeChangedDataDelta}
+ * payload describing both shallow and deep changes.
+ * For non-array nodes, the `treeChanged` signature is the same as the base event.
+ *
  * Use via `TreeAlpha.on`.
  * @sealed @alpha
  */
 export interface TreeChangeEventsAlpha<TNode extends TreeNode = TreeNode>
 	extends TreeChangeEvents {
 	/**
-	 * Like `TreeChangeEventsBeta.nodeChanged`, but for array nodes the event data includes
-	 * a {@link NodeChangedDataDelta.delta | delta} payload describing the changes as a sequence
-	 * of {@link ArrayNodeDeltaOp} values.
+	 * Emitted when a shallow change occurs on this node, i.e., when the node's direct children change.
 	 *
 	 * @remarks
+	 * For array nodes: the event data includes a {@link NodeChangedDataDelta.delta | delta} payload
+	 * as a sequence of {@link ArrayNodeDeltaOp} values. Does not fire for deep changes (e.g. a
+	 * property of an array element changed without any shallow array change). Subscribe to
+	 * {@link TreeChangeEventsAlpha.treeChanged} on the array to receive a delta for those cases as well.
+	 *
+	 * For object, map, and record nodes: the event data includes
+	 * {@link NodeChangedDataProperties.changedProperties | changedProperties}.
+	 * @privateRemarks
 	 * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
 	 */
 	nodeChanged: (data: NodeChangedDataAlpha<TNode>) => void;
+
+	/**
+	 * Emitted when something in the subtree rooted at this node changes.
+	 *
+	 * @remarks
+	 * For array nodes: emitted when any change occurred within the array, including both
+	 * shallow changes (insert, remove, move) and deep changes (e.g. a property of an element
+	 * changed). The event data carries a {@link NodeChangedDataTreeDelta.delta | delta} payload
+	 * describing what changed. The delta uses {@link ArrayNodeTreeChangedRetainOp.subtreeChanged}
+	 * to flag elements that have deep changes, without describing the details of those deep changes.
+	 * To inspect deep changes, subscribe to `nodeChanged` or `treeChanged` on the individual
+	 * element nodes.
+	 *
+	 * When this array is nested inside another array, the outer array's `treeChanged` still
+	 * fires with a delta, but that delta only shows `subtreeChanged: true` for the element
+	 * position containing this inner array — it does not include the inner array's detailed
+	 * insert/remove/retain ops. To receive those detailed ops, subscribe to `treeChanged`
+	 * directly on the inner array.
+	 * Ancestor non-array nodes still receive the base (no-payload) `treeChanged` via normal
+	 * subtree propagation.
+	 *
+	 * For non-array nodes: same as the base {@link TreeChangeEvents.treeChanged}.
+	 * @privateRemarks
+	 * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
+	 */
+	treeChanged: TNode extends WithType<string, NodeKind.Array>
+		? (data: NodeChangedDataTreeDelta) => void
+		: TreeChangeEventsBeta<TNode>["treeChanged"];
 }

package/src/simple-tree/api/treeChangeEvents.ts

@@ -36,7 +36,7 @@ export interface TreeChangeEvents {
 	 *
 	 * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).
 	 *
-	 * - Array nodes define a change as when an element is added, removed, moved or replaced.
+	 * - Array nodes define a change as when an element is added, removed, moved, or replaced.
 	 *
 	 * - Map nodes define a change as when an entry is added, updated, or removed.
 	 *

package/src/simple-tree/api/treeNodeApi.ts

@@ -41,7 +41,7 @@ import type { TreeChangeEvents } from "./treeChangeEvents.js";
 
 /**
  * A `"retain"` op in an {@link ArrayNodeDeltaOp} sequence.
- * Represents elements that were not added or removed (though they may have nested changes).
+ * Represents elements that were neither inserted into nor removed from the array.
  * @sealed @alpha
  */
 export interface ArrayNodeRetainOp {
@@ -49,6 +49,36 @@ export interface ArrayNodeRetainOp {
 	readonly count: number;
 }
 
+/**
+ * A `"retain"` op in an {@link ArrayNodeTreeChangedDeltaOp} sequence, used in
+ * {@link NodeChangedDataTreeDelta} payloads delivered to
+ * {@link TreeChangeEventsAlpha.treeChanged} on array nodes.
+ *
+ * Extends {@link ArrayNodeRetainOp} with a {@link ArrayNodeTreeChangedRetainOp.subtreeChanged}
+ * flag that indicates whether any descendant of the retained element changed.
+ * @sealed @alpha
+ */
+export interface ArrayNodeTreeChangedRetainOp extends ArrayNodeRetainOp {
+	/**
+	 * Whether any descendant of this retained element changed.
+	 * `true` if the element's subtree changed; `false` if nothing changed within it.
+	 * @remarks
+	 * Subscribe to `nodeChanged` or `treeChanged` on the element node itself for details.
+	 */
+	readonly subtreeChanged: boolean;
+}
+
+/**
+ * A single operation in an array-node delta delivered by {@link TreeChangeEventsAlpha.treeChanged}.
+ * Extends {@link ArrayNodeDeltaOp}: retain ops carry a {@link ArrayNodeTreeChangedRetainOp.subtreeChanged}
+ * flag indicating whether any descendant of the retained element changed.
+ * @alpha
+ */
+export type ArrayNodeTreeChangedDeltaOp =
+	| ArrayNodeTreeChangedRetainOp
+	| ArrayNodeInsertOp
+	| ArrayNodeRemoveOp;
+
 /**
  * An `"insert"` op in an {@link ArrayNodeDeltaOp} sequence.
  * Represents elements added to the array.
@@ -247,13 +277,25 @@ export const treeNodeApi: TreeNodeApi = {
 				} else if (isArrayNodeSchema(nodeSchema)) {
 					return kernel.events.on("childrenChangedAfterBatch", ({ fieldMarks }) => {
 						const marks = fieldMarks.get(EmptyKey);
+						// nodeChanged fires only for shallow changes (insert, remove, move).
+						// Deep changes (e.g. a property of an element changed) are
+						// surfaced via TreeChangeEventsAlpha.treeChanged with a delta payload instead.
+						// When marks are undefined (marks could not be composed across multiple
+						// internal passes), we conservatively fire nodeChanged rather than silently
+						// dropping the event, even though the underlying change may have been
+						// purely deep. This is a known limitation of the current eventing stack.
+						const hasShallowChange =
+							marks === undefined ||
+							marks.some((m) => m.attach !== undefined || m.detach !== undefined);
+						if (!hasShallowChange) {
+							return;
+						}
 						// `marks` is undefined when the field was modified across multiple batches
 						// within a single flush (e.g. due to an interleaved schema change) and the
 						// marks could not be composed. Emit `undefined` so callers know the delta is
 						// unavailable rather than receiving stale marks from only the first batch.
 						// TODO: Once the eventing stack is rewritten to walk the composed delta at
-						// flush time, `marks` will always be defined. Remove the `undefined` fallback
-						// and simplify to: `const delta = deltaMarksToArrayOps(marks);`
+						// flush time, `marks` will always be defined. Remove the `undefined` fallback.
 						const delta = marks === undefined ? undefined : deltaMarksToArrayOps(marks);
 						listener({ delta });
 					});
@@ -264,6 +306,18 @@ export const treeNodeApi: TreeNodeApi = {
 				}
 			}
 			case "treeChanged": {
+				if (isArrayNodeSchema(kernel.schema)) {
+					// For array nodes, treeChanged fires via childrenChangedAfterBatch so that a
+					// delta payload can be provided. This covers both shallow changes
+					// (insert/remove/move) and deep element changes. Stable (non-alpha) listeners
+					// typed as () => void will silently ignore the extra argument at runtime.
+					return kernel.events.on("childrenChangedAfterBatch", ({ fieldMarks }) => {
+						const marks = fieldMarks.get(EmptyKey);
+						const delta =
+							marks === undefined ? undefined : deltaMarksToArrayOpsForTreeChanged(marks);
+						(listener as (data: { readonly delta: typeof delta }) => void)({ delta });
+					});
+				}
 				return kernel.events.on("subtreeChangedAfterBatch", () => listener({}));
 			}
 			default: {
@@ -298,19 +352,21 @@ export const treeNodeApi: TreeNodeApi = {
 
 /**
  * Converts an array of internal {@link DeltaMark}s for a sequence field into sequential
- * array delta ops suitable for inclusion in {@link NodeChangedData.delta}.
+ * array delta ops suitable for inclusion in {@link NodeChangedDataDelta.delta}.
  *
  * Each mark in the delta describes a contiguous run of positions in the original array:
- * - A mark with only `count` (no attach/detach) → `"retain"` (elements unchanged at this level)
+ * - A mark with only `count` (no attach/detach) → `"retain"` with no subtree information
  * - A mark with only `attach` → `"insert"` (new elements added)
  * - A mark with only `detach` → `"remove"` (elements removed)
  * - A mark with both `attach` and `detach` → `"remove"` + `"insert"`
  *
+ * @param marks - The low-level delta marks for the array's sequence field.
+ *
  * @privateRemarks
  * The case where both `attach` and `detach` are set is unreachable today: the sequence-field
  * encoder never emits such marks for array (EmptyKey) fields. It is handled defensively.
  */
-function deltaMarksToArrayOps(marks: readonly DeltaMark[]): ArrayNodeDeltaOp[] {
+export function deltaMarksToArrayOps(marks: readonly DeltaMark[]): ArrayNodeDeltaOp[] {
 	const ops: ArrayNodeDeltaOp[] = [];
 	for (const mark of marks) {
 		if (mark.detach !== undefined) {
@@ -319,13 +375,51 @@ function deltaMarksToArrayOps(marks: readonly DeltaMark[]): ArrayNodeDeltaOp[] {
 		if (mark.attach !== undefined) {
 			ops.push({ type: "insert", count: mark.count });
 		} else if (mark.detach === undefined) {
-			// Neither attach nor detach: elements retained (may have nested changes in mark.fields).
+			// Retain: elements were not added or removed.
 			ops.push({ type: "retain", count: mark.count });
 		}
 	}
 	return ops;
 }
 
+/**
+ * Converts an array of internal {@link DeltaMark}s for a sequence field into sequential
+ * {@link ArrayNodeTreeChangedDeltaOp}s suitable for inclusion in
+ * {@link NodeChangedDataTreeDelta.delta} (delivered to {@link TreeChangeEventsAlpha.treeChanged}).
+ *
+ * Same conversion rules as {@link deltaMarksToArrayOps}, but retain ops additionally carry a
+ * {@link ArrayNodeTreeChangedRetainOp.subtreeChanged} flag derived from whether the mark has
+ * a `fields` property (indicating a descendant changed).
+ *
+ * @param marks - The low-level delta marks for the array's sequence field.
+ *
+ * @privateRemarks
+ * The case where both `attach` and `detach` are set is unreachable today: the sequence-field
+ * encoder never emits such marks for array (EmptyKey) fields. It is handled defensively.
+ */
+export function deltaMarksToArrayOpsForTreeChanged(
+	marks: readonly DeltaMark[],
+): ArrayNodeTreeChangedDeltaOp[] {
+	const ops: ArrayNodeTreeChangedDeltaOp[] = [];
+	for (const mark of marks) {
+		if (mark.detach !== undefined) {
+			ops.push({ type: "remove", count: mark.count });
+		}
+		if (mark.attach !== undefined) {
+			ops.push({ type: "insert", count: mark.count });
+		} else if (mark.detach === undefined) {
+			// Retain: elements were not added or removed (but may have deep changes).
+			// When `fields` is set, `count` is guaranteed to be 1 (DeltaMark invariant).
+			ops.push({
+				type: "retain",
+				count: mark.count,
+				subtreeChanged: mark.fields !== undefined,
+			});
+		}
+	}
+	return ops;
+}
+
 /**
  * Returns a schema for a value if the value is a {@link TreeNode} or a {@link TreeLeafValue}.
  * Returns undefined for other values.

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

@@ -15,6 +15,14 @@ export interface StoredFromViewSchemaGenerationOptions {
 	 * Due to caching, the behavior of this function must be pure.
 	 */
 	includeStaged(upgrade: SchemaUpgrade): boolean;
+
+	/**
+	 * Determines whether to treat a {@link SchemaFactoryAlpha.stagedOptional | staged optional} field as optional
+	 * (rather than required) in the resulting stored schema.
+	 * @remarks
+	 * Due to caching, the behavior of this function must be pure.
+	 */
+	includeStagedOptional(upgrade: SchemaUpgrade): boolean;
 }
 
 /**

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

@@ -11,6 +11,9 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import {
 	type AnchorEvents,
 	dummyRoot,
+	EmptyKey,
+	type DeltaDetachedNodeId,
+	type DeltaMark,
 	type FieldKey,
 	type FieldKindIdentifier,
 	type ITreeCursorSynchronous,
@@ -84,6 +87,13 @@ type UnhydratedFlexTreeNodeEvents = Pick<
 /** A node's parent field and its index in that field */
 type LocationInField = FlexTreeNode["parentField"];
 
+/**
+ * Placeholder `DeltaDetachedNodeId` used as the attach/detach id in synthetic delta marks produced
+ * by the unhydrated sequence-field editor. Only the *presence* of the id is checked by
+ * {@link deltaMarksToArrayOps}, so the value itself is arbitrary.
+ */
+const syntheticDetachedNodeId: DeltaDetachedNodeId = { minor: 0 };
+
 /**
  * The {@link Unhydrated} implementation of {@link FlexTreeNode}.
  */
@@ -270,24 +280,88 @@ export class UnhydratedFlexTreeNode
 		return this.data.value;
 	}
 
-	public emitChangedEvent(key: FieldKey): void {
+	/**
+	 * Emit a `childrenChangedAfterBatch` event for this node, then propagate deep-change
+	 * signals to ancestor array nodes and subtree-changed signals up the entire ancestor chain.
+	 * @param key - The field key that changed.
+	 * @param marks - Optional delta marks describing the change to the field. When provided, they
+	 * are included in the `fieldMarks` payload so that array-node listeners can build a delta.
+	 * When omitted (e.g. for non-sequence fields), `fieldMarks` is empty.
+	 */
+	public emitChangedEvent(key: FieldKey, marks?: readonly DeltaMark[]): void {
 		this._events.emit("childrenChangedAfterBatch", {
 			changedFields: new Set([key]),
-			// Unhydrated nodes are not visited by the delta pipeline, so no field marks are available.
-			fieldMarks: new Map(),
+			fieldMarks: marks === undefined ? new Map() : new Map([[key, marks]]),
 		});
 
-		// Also emit subtree changed event for this node and all ancestors.
+		// Emit subtree-changed events for this node and its non-array ancestors first,
+		// so that node.treeChanged fires before any ancestor array.treeChanged.
+		// Array ancestors and the nodes above them are handled by
+		// #emitDeepChangesToAncestorArrays, which propagates subtree events above
+		// each array boundary in the correct order.
 		this.#emitSubtreeChangedEvents();
+
+		// Mirrors the onlyDeepChanges block in anchorSet.ts for unhydrated nodes.
+		this.#emitDeepChangesToAncestorArrays();
 	}
 
 	/**
-	 * Emit subtree changed events for this node and all ancestors.
+	 * Emit `childrenChangedAfterBatch` on each ancestor array node with synthetic
+	 * marks indicating a deep change at this node's position within the array.
+	 * After emitting on each array ancestor, propagates subtree-changed events
+	 * upward from that array so that ancestor nodes above the array receive their
+	 * `treeChanged` events after the array's own event.
+	 */
+	#emitDeepChangesToAncestorArrays(): void {
+		const location = this.parentField;
+		const parentField = location.parent;
+		const parentNode = parentField.parent;
+
+		if (parentNode === undefined || !(parentNode instanceof UnhydratedFlexTreeNode)) {
+			return;
+		}
+
+		// Only emit on array ancestors (EmptyKey); object/map ancestors don't carry delta payloads.
+		if (parentField.key === EmptyKey) {
+			const index = location.index;
+			const syntheticMarks: DeltaMark[] = [];
+			if (index > 0) {
+				syntheticMarks.push({ count: index });
+			}
+			// `fields` presence (not content) signals a deep change to deltaMarksToArrayOps.
+			syntheticMarks.push({ count: 1, fields: new Map([[EmptyKey, { marks: [] }]]) });
+
+			parentNode._events.emit("childrenChangedAfterBatch", {
+				changedFields: new Set([EmptyKey]),
+				fieldMarks: new Map([[EmptyKey, syntheticMarks]]),
+			});
+
+			// Propagate subtree-changed events from the array upward so that
+			// ancestors above this array receive treeChanged after the array itself.
+			parentNode.#emitSubtreeChangedEvents();
+		}
+
+		parentNode.#emitDeepChangesToAncestorArrays();
+	}
+
+	/**
+	 * Emit `subtreeChangedAfterBatch` on this node and propagate upward to
+	 * ancestors, stopping before the first ancestor array node.
+	 * Propagation stops at an array boundary because
+	 * {@link UnhydratedFlexTreeNode.#emitDeepChangesToAncestorArrays} is
+	 * responsible for emitting on array ancestors and the nodes above them
+	 * in the correct order.
 	 */
 	#emitSubtreeChangedEvents(): void {
 		this._events.emit("subtreeChangedAfterBatch");
 
-		const parent = this.parentField.parent.parent;
+		const parentField = this.parentField.parent;
+		if (parentField.key === EmptyKey) {
+			// This node is an array element; stop here so that array ancestor
+			// events fire in the correct order relative to this node's treeChanged.
+			return;
+		}
+		const parent = parentField.parent;
 		assert(
 			parent === undefined || parent instanceof UnhydratedFlexTreeNode,
 			0xb76 /* Unhydrated node's parent should be an unhydrated node */,
@@ -445,6 +519,12 @@ export class UnhydratedFlexTreeField
 	 */
 	protected edit(
 		edit: (mapTrees: UnhydratedFlexTreeNode[]) => void | UnhydratedFlexTreeNode[],
+		/**
+		 * Delta marks describing this edit, forwarded to {@link UnhydratedFlexTreeNode.emitChangedEvent}.
+		 * Sequence-field subclasses pass pre-computed marks so that array-node listeners receive a
+		 * meaningful delta; other field kinds omit this parameter.
+		 */
+		marks?: readonly DeltaMark[],
 	): void {
 		// Clear parents for all old map trees.
 		for (const tree of this.children) {
@@ -458,7 +538,7 @@ export class UnhydratedFlexTreeField
 			tree.adoptBy(this, index);
 		}
 
-		this.parent?.emitChangedEvent(this.key);
+		this.parent?.emitChangedEvent(this.key, marks);
 	}
 
 	public getFieldPath(): NormalizedFieldUpPath {
@@ -541,6 +621,10 @@ export class UnhydratedSequenceField
 				assert(c instanceof UnhydratedFlexTreeNode, 0xbb8 /* Expected unhydrated node */);
 			}
 			const newContentChecked = newContent as readonly UnhydratedFlexTreeNode[];
+			const insertCount = newContentChecked.length;
+			const marks: DeltaMark[] = [];
+			if (index > 0) marks.push({ count: index });
+			marks.push({ count: insertCount, attach: syntheticDetachedNodeId });
 			this.edit((mapTrees) => {
 				if (newContent.length < 1000) {
 					// For "smallish arrays" (`1000` is not empirically derived), the `splice` function is appropriate...
@@ -549,23 +633,27 @@ export class UnhydratedSequenceField
 					// ...but we avoid using `splice` + spread for very large input arrays since there is a limit on how many elements can be spread (too many will overflow the stack).
 					return [...mapTrees.slice(0, index), ...newContentChecked, ...mapTrees.slice(index)];
 				}
-			});
+			}, marks);
 		},
 		remove: (index, count): UnhydratedFlexTreeNode[] => {
 			for (let i = index; i < index + count; i++) {
 				const c = this.children[i];
 				assert(c !== undefined, 0xa0b /* Unexpected sparse array */);
 			}
+			const marks: DeltaMark[] = [];
+			if (index > 0) marks.push({ count: index });
+			marks.push({ count, detach: syntheticDetachedNodeId });
 			let removed: UnhydratedFlexTreeNode[] | undefined;
 			this.edit((mapTrees) => {
 				removed = mapTrees.splice(index, count);
-			});
+			}, marks);
 			return removed ?? fail(0xb4a /* Expected removed to be set by edit */);
 		},
 		move: (sourceIndex, count, destIndex, source?): void => {
 			const sourceField = source ?? this;
 			if (sourceField === this) {
 				// Within-field move: do both operations in a single edit to emit only one event
+				const marks = buildUnhydratedMoveMarks(sourceIndex, count, destIndex);
 				this.edit((mapTrees) => {
 					const removed = mapTrees.splice(sourceIndex, count);
 					// Adjust destination index if it comes after the source
@@ -581,7 +669,7 @@ export class UnhydratedSequenceField
 							...mapTrees.slice(adjustedDest),
 						];
 					}
-				});
+				}, marks);
 			} else {
 				// Cross-field move: remove from source, insert into destination
 				// Each field emits one event (correct behavior for different fields)
@@ -605,6 +693,42 @@ export class UnhydratedSequenceField
 
 // #endregion Fields
 
+/**
+ * Builds {@link DeltaMark}s describing a within-field move for use in
+ * {@link UnhydratedFlexTreeNode.emitChangedEvent}.
+ *
+ * @remarks
+ * Forward move (`sourceIndex < destIndex`):
+ * `[retain(src), detach(n), retain(mid), attach(n)]`
+ *
+ * Backward move (`destIndex < sourceIndex`):
+ * `[retain(dst), attach(n), retain(mid), detach(n)]`
+ *
+ * A no-op move (`sourceIndex === destIndex`) returns an empty array; the event
+ * should not fire in that case, but the empty marks are harmless if it does.
+ */
+function buildUnhydratedMoveMarks(
+	sourceIndex: number,
+	count: number,
+	destIndex: number,
+): readonly DeltaMark[] {
+	const marks: DeltaMark[] = [];
+	if (sourceIndex < destIndex) {
+		if (sourceIndex > 0) marks.push({ count: sourceIndex });
+		marks.push({ count, detach: syntheticDetachedNodeId });
+		const between = destIndex - sourceIndex - count;
+		if (between > 0) marks.push({ count: between });
+		marks.push({ count, attach: syntheticDetachedNodeId });
+	} else if (destIndex < sourceIndex) {
+		if (destIndex > 0) marks.push({ count: destIndex });
+		marks.push({ count, attach: syntheticDetachedNodeId });
+		const between = sourceIndex - destIndex;
+		if (between > 0) marks.push({ count: between });
+		marks.push({ count, detach: syntheticDetachedNodeId });
+	}
+	return marks;
+}
+
 /** Creates a field with the given attributes */
 export function createField(
 	...args: ConstructorParameters<typeof UnhydratedFlexTreeField>

package/src/simple-tree/fieldSchema.ts

@@ -28,6 +28,7 @@ import type {
 	TreeLeafValue,
 	InsertableTreeNodeFromImplicitAllowedTypes,
 	AllowedTypesFull,
+	SchemaUpgrade,
 } from "./core/index.js";
 import { AnnotatedAllowedTypesInternal, normalizeAllowedTypes } from "./core/index.js";
 import type {
@@ -182,6 +183,11 @@ export interface FieldPropsAlpha<TCustomMetadata = unknown>
 	 * Sets {@link SimpleFieldSchema.persistedMetadata}.
 	 */
 	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
+
+	/**
+	 * If defined, indicates that this field is a {@link SchemaStaticsAlpha.stagedOptional | staged optional} field.
+	 */
+	readonly stagedOptionalUpgrade?: SchemaUpgrade;
 }
 
 /**
@@ -412,6 +418,10 @@ export class FieldSchemaAlpha<
 		return this.propsAlpha?.persistedMetadata;
 	}
 
+	public get isStagedOptional(): false | SchemaUpgrade {
+		return this.propsAlpha?.stagedOptionalUpgrade ?? false;
+	}
+
 	static {
 		createFieldSchemaPrivate = <
 			Kind2 extends FieldKind,

package/src/simple-tree/index.ts

@@ -95,10 +95,14 @@ export {
 	type ArrayNodeInsertOp,
 	type ArrayNodeRemoveOp,
 	type ArrayNodeRetainOp,
+	type ArrayNodeTreeChangedDeltaOp,
+	type ArrayNodeTreeChangedRetainOp,
+	deltaMarksToArrayOps,
 	type NodeChangedData,
 	type NodeChangedDataAlpha,
 	type NodeChangedDataDelta,
 	type NodeChangedDataProperties,
+	type NodeChangedDataTreeDelta,
 	borrowCursorFromTreeNodeOrValue,
 	exportConcise,
 	importConcise,
@@ -270,6 +274,7 @@ export {
 	MapNodeSchema,
 	isMapNodeSchema,
 	type TreeMapNode,
+	type TreeMapNodeAlpha,
 	type MapNodeInsertableData,
 	type FieldHasDefault,
 	type FieldHasDefaultAlpha,

package/src/simple-tree/node-kinds/index.ts

@@ -27,6 +27,7 @@ export {
 	MapNodeSchema,
 	mapSchema,
 	type TreeMapNode,
+	type TreeMapNodeAlpha,
 } from "./map/index.js";
 
 export {

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

@@ -7,6 +7,7 @@ export {
 	type MapNodeInsertableData,
 	mapSchema,
 	type TreeMapNode,
+	type TreeMapNodeAlpha,
 } from "./mapNode.js";
 export {
 	isMapNodeSchema,