@fluidframework/tree 2.91.0 → 2.93.0

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

@@ -8,7 +8,7 @@ import { assert, oob, fail, unreachableCase } from "@fluidframework/core-utils/i
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey, rootFieldKey } from "../../core/index.js";
+import { EmptyKey, rootFieldKey, type DeltaMark } from "../../core/index.js";
 import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
 import { extractFromOpaque } from "../../util/index.js";
 import {
@@ -39,6 +39,86 @@ import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";
 
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
 
+/**
+ * A `"retain"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements that were neither inserted into nor removed from the array.
+ * @sealed @alpha
+ */
+export interface ArrayNodeRetainOp {
+	readonly type: "retain";
+	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.
+ * Read the new element values from the current tree at the positions described by this op.
+ * @sealed @alpha
+ */
+export interface ArrayNodeInsertOp {
+	readonly type: "insert";
+	readonly count: number;
+}
+
+/**
+ * A `"remove"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements removed from the array.
+ * @sealed @alpha
+ */
+export interface ArrayNodeRemoveOp {
+	readonly type: "remove";
+	readonly count: number;
+}
+
+/**
+ * A single operation in an array node change delta. Used to efficiently sync an external
+ * representation of an array (e.g. a text editor or virtual list) with tree changes without
+ * needing to snapshot the old state or diff the entire array. Each op describes a contiguous run
+ * of positions in the array before the change. For inserts, read the new element values from the
+ * current tree at those positions.
+ *
+ * @remarks
+ * There is no dedicated `"move"` op. Moves are represented as `"remove"` + `"insert"`.
+ * When an element is moved within the same array it appears
+ * as a `"remove"` at the source position followed by an `"insert"` at the destination position.
+ * When an element is moved across two different arrays, the source array's delta contains a
+ * `"remove"` and the destination array's delta contains an `"insert"` — they cannot be
+ * correlated without additional bookkeeping on the caller's side.
+ *
+ * @sealed @alpha
+ */
+export type ArrayNodeDeltaOp = ArrayNodeRetainOp | ArrayNodeInsertOp | ArrayNodeRemoveOp;
+
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
  *
@@ -105,6 +185,9 @@ export interface TreeNodeApi {
 	 * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.
 	 * @returns A callback function which will deregister the event.
 	 * This callback should be called only once.
+	 * @remarks
+	 * The returned unsubscribe function should be called any time the need for the `listener` callback ends before the node is {@link TreeStatus.Deleted | deleted} (Not just {@link TreeStatus.Removed | removed}).
+	 * Doing so removes the overhead of tracking and triggering the event, and also avoids leaking any memory retained by the callback.
 	 */
 	on<K extends keyof TreeChangeEvents>(
 		node: TreeNode,
@@ -192,8 +275,29 @@ export const treeNodeApi: TreeNodeApi = {
 						listener({ changedProperties });
 					});
 				} else if (isArrayNodeSchema(nodeSchema)) {
-					return kernel.events.on("childrenChangedAfterBatch", () => {
-						listener({ changedProperties: undefined });
+					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.
+						const delta = marks === undefined ? undefined : deltaMarksToArrayOps(marks);
+						listener({ delta });
 					});
 				} else {
 					return kernel.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
@@ -202,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: {
@@ -234,6 +350,76 @@ 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 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"` 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.
+ */
+export function deltaMarksToArrayOps(marks: readonly DeltaMark[]): ArrayNodeDeltaOp[] {
+	const ops: ArrayNodeDeltaOp[] = [];
+	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.
+			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/treeNodeKernel.ts

@@ -17,6 +17,7 @@ import {
 	anchorSlot,
 	type AnchorEvents,
 	type AnchorNode,
+	type DeltaMark,
 	type FieldKey,
 	type TreeValue,
 } from "../../core/index.js";
@@ -362,6 +363,20 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 	 */
 	readonly #childrenChangedBuffer: Set<FieldKey> = new Set();
 
+	/**
+	 * Buffer of field marks accumulated since events were paused.
+	 * Emitted alongside the buffered changed-fields set when flushed.
+	 */
+	readonly #fieldMarksBuffer: Map<FieldKey, readonly DeltaMark[]> = new Map();
+
+	/**
+	 * Fields whose marks have been permanently invalidated within the current buffer window due to
+	 * two or more separate delta batches touching the same field.
+	 * Once a key is in this set it must never be re-added to the marks buffer, even if
+	 * a third (or later) batch arrives for that field.
+	 */
+	readonly #invalidatedFieldMarkKeys: Set<FieldKey> = new Set();
+
 	/**
 	 * Whether or not the subtree has changed since events were paused.
 	 * When events are flushed, a single {@link AnchorEvents.subTreeChanged} event will be emitted if and only
@@ -399,8 +414,10 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		this.#eventSource = newSource;
 
 		if (this.#events.hasListeners("childrenChangedAfterBatch")) {
-			const off = this.#eventSource.on("childrenChangedAfterBatch", ({ changedFields }) =>
-				this.#emit("childrenChangedAfterBatch", { changedFields }),
+			const off = this.#eventSource.on(
+				"childrenChangedAfterBatch",
+				({ changedFields, fieldMarks }) =>
+					this.#emit("childrenChangedAfterBatch", { changedFields, fieldMarks }),
 			);
 			this.#disposeSourceListeners.set("childrenChangedAfterBatch", off);
 		}
@@ -421,7 +438,10 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 				0xc4f /* Should not have a dispose function without listeners */,
 			);
 
-			const off = this.#eventSource.on(eventName, (args) => this.#emit(eventName, args));
+			const off: Off =
+				eventName === "childrenChangedAfterBatch"
+					? this.#eventSource.on(eventName, (args) => this.#emit(eventName, args))
+					: this.#eventSource.on(eventName, () => this.#emit(eventName));
 			this.#disposeSourceListeners.set(eventName, off);
 		}
 
@@ -444,13 +464,14 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		eventName: keyof KernelEvents,
 		arg?: {
 			changedFields: ReadonlySet<FieldKey>;
+			fieldMarks: ReadonlyMap<FieldKey, readonly DeltaMark[]>;
 		},
 	): void {
 		this.#assertNotDisposed();
 		switch (eventName) {
 			case "childrenChangedAfterBatch": {
-				assert(arg !== undefined, 0xc50 /* childrenChangedAfterBatch should have arg */);
-				return this.#handleChildrenChangedAfterBatch(arg.changedFields);
+				assert(arg !== undefined, 0xcea /* childrenChangedAfterBatch requires arg */);
+				return this.#handleChildrenChangedAfterBatch(arg.changedFields, arg.fieldMarks);
 			}
 			case "subtreeChangedAfterBatch": {
 				return this.#handleSubtreeChangedAfterBatch();
@@ -461,13 +482,33 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		}
 	}
 
-	#handleChildrenChangedAfterBatch(changedFields: ReadonlySet<FieldKey>): void {
+	#handleChildrenChangedAfterBatch(
+		changedFields: ReadonlySet<FieldKey>,
+		fieldMarks: ReadonlyMap<FieldKey, readonly DeltaMark[]>,
+	): void {
 		if (bufferTreeEvents) {
 			for (const fieldKey of changedFields) {
 				this.#childrenChangedBuffer.add(fieldKey);
 			}
+			for (const [key, marks] of fieldMarks) {
+				if (this.#invalidatedFieldMarkKeys.has(key)) {
+					// Already permanently invalidated by an earlier collision; ignore this batch too.
+					// TODO: Once the eventing stack is rewritten to walk the composed delta at flush
+					// time, this collision path will be unreachable and can be removed entirely.
+					continue;
+				}
+				if (this.#fieldMarksBuffer.has(key)) {
+					// A second batch of marks arrived for the same field before the buffer was flushed.
+					// We have no delta composition logic, so permanently invalidate this field so that
+					// any further batches are also discarded rather than incorrectly surfaced.
+					this.#fieldMarksBuffer.delete(key);
+					this.#invalidatedFieldMarkKeys.add(key);
+				} else {
+					this.#fieldMarksBuffer.set(key, marks);
+				}
+			}
 		} else {
-			this.#events.emit("childrenChangedAfterBatch", { changedFields });
+			this.#events.emit("childrenChangedAfterBatch", { changedFields, fieldMarks });
 		}
 	}
 
@@ -488,8 +529,11 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		if (this.#childrenChangedBuffer.size > 0) {
 			this.#events.emit("childrenChangedAfterBatch", {
 				changedFields: this.#childrenChangedBuffer,
+				fieldMarks: this.#fieldMarksBuffer,
 			});
 			this.#childrenChangedBuffer.clear();
+			this.#fieldMarksBuffer.clear();
+			this.#invalidatedFieldMarkKeys.clear();
 		}
 
 		if (this.#subTreeChangedBuffer) {
@@ -519,6 +563,8 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		this.#disposeSourceListeners.clear();
 
 		this.#childrenChangedBuffer.clear();
+		this.#fieldMarksBuffer.clear();
+		this.#invalidatedFieldMarkKeys.clear();
 		this.#subTreeChangedBuffer = false;
 
 		this.#disposed = true;

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,20 +280,88 @@ export class UnhydratedFlexTreeNode
 		return this.data.value;
 	}
 
-	public emitChangedEvent(key: FieldKey): void {
-		this._events.emit("childrenChangedAfterBatch", { changedFields: new Set([key]) });
+	/**
+	 * 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]),
+			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 `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 subtree changed events for this node and all ancestors.
+	 * 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 */,
@@ -441,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) {
@@ -454,7 +538,7 @@ export class UnhydratedFlexTreeField
 			tree.adoptBy(this, index);
 		}
 
-		this.parent?.emitChangedEvent(this.key);
+		this.parent?.emitChangedEvent(this.key, marks);
 	}
 
 	public getFieldPath(): NormalizedFieldUpPath {
@@ -537,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...
@@ -545,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
@@ -577,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)
@@ -601,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

@@ -91,12 +91,24 @@ export {
 	singletonSchema,
 	treeNodeApi,
 	type TreeNodeApi,
+	type ArrayNodeDeltaOp,
+	type ArrayNodeInsertOp,
+	type ArrayNodeRemoveOp,
+	type ArrayNodeRetainOp,
+	type ArrayNodeTreeChangedDeltaOp,
+	type ArrayNodeTreeChangedRetainOp,
+	deltaMarksToArrayOps,
 	type NodeChangedData,
+	type NodeChangedDataAlpha,
+	type NodeChangedDataDelta,
+	type NodeChangedDataProperties,
+	type NodeChangedDataTreeDelta,
 	borrowCursorFromTreeNodeOrValue,
 	exportConcise,
 	importConcise,
 	TreeBeta,
 	type TreeChangeEventsBeta,
+	type TreeChangeEventsAlpha,
 	type IdentifierIndex,
 	createTreeIndex,
 	createIdentifierIndex,
@@ -248,6 +260,7 @@ export {
 export { tryGetTreeNodeForField } from "./getTreeNodeForField.js";
 export {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	type ArrayNodePojoEmulationSchema,
 	ArrayNodeSchema,
 	asIndex,
@@ -255,11 +268,13 @@ export {
 	IterableTreeArrayContent,
 	type ReadonlyArrayNode,
 	TreeArrayNode,
+	type TreeArrayNodeAlpha,
 	type MapNodeCustomizableSchema,
 	type MapNodePojoEmulationSchema,
 	MapNodeSchema,
 	isMapNodeSchema,
 	type TreeMapNode,
+	type TreeMapNodeAlpha,
 	type MapNodeInsertableData,
 	type FieldHasDefault,
 	type FieldHasDefaultAlpha,