@fluidframework/tree 2.23.0 → 2.31.0

package/src/core/tree/anchorSet.ts

@@ -5,7 +5,7 @@
 
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 
 import type { Listenable } from "@fluidframework/core-interfaces/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
@@ -17,16 +17,24 @@ import {
 	ReferenceCountedBase,
 	brand,
 	brandedSlot,
-	fail,
 	getOrAddEmptyToMap,
 	getOrCreate,
 } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type * as Delta from "./delta.js";
-import type { PlaceIndex, Range, UpPath } from "./pathTree.js";
+import {
+	isDetachedUpPathRoot,
+	type INormalizedUpPath,
+	type NormalizedUpPath,
+	type PlaceIndex,
+	type Range,
+	type UpPath,
+} from "./pathTree.js";
 import { EmptyKey } from "./types.js";
 import type { DeltaVisitor } from "./visitDelta.js";
+import { offsetDetachId } from "./deltaUtil.js";
+import type { ITreeCursorSynchronous } from "./cursor.js";
 
 /**
  * A way to refer to a particular tree location within an {@link AnchorSet}.
@@ -198,7 +206,7 @@ export interface AnchorSetRootEvents {
 /**
  * Node in a tree of anchors.
  */
-export interface AnchorNode extends UpPath<AnchorNode> {
+export interface AnchorNode extends INormalizedUpPath<AnchorNode> {
 	/**
 	 * Events for this anchor node.
 	 */
@@ -569,6 +577,13 @@ export class AnchorSet implements AnchorLocator {
 			node.parentIndex += destination.parentIndex - coupleInfo.startParentIndex;
 			node.parentPath = destinationPath;
 			node.parentField = destination.parentField;
+			// If the destination is a detached root, propagate its detachedNodeId, otherwise remove any existing one
+			node.detachedNodeId = isDetachedUpPathRoot(destination)
+				? offsetDetachId(
+						destination.detachedNodeId,
+						node.parentIndex - destination.parentIndex,
+					)
+				: undefined;
 		}
 
 		// Update new parent to add children
@@ -821,25 +836,34 @@ export class AnchorSet implements AnchorLocator {
 				this.anchorSet.moveChildren(sourcePath, destinationPath, count);
 				this.depthThresholdForSubtreeChanged = this.currentDepth;
 			},
-			detach(source: Range, destination: FieldKey): void {
+			detach(
+				source: Range,
+				destination: FieldKey,
+				detachedNodeId: Delta.DetachedNodeId,
+			): void {
 				this.notifyChildrenChanging();
-				this.detachEdit(source, destination);
+				this.detachEdit(source, destination, detachedNodeId);
 				this.notifyChildrenChanged();
 			},
-			detachEdit(source: Range, destination: FieldKey): void {
+			detachEdit(
+				source: Range,
+				destination: FieldKey,
+				detachedNodeId: Delta.DetachedNodeId,
+			): void {
 				assert(
 					this.parentField !== undefined,
 					0x7a5 /* Must be in a field in order to detach */,
 				);
-				const sourcePath = {
+				const sourcePath: UpPath = {
 					parent: this.parent,
 					parentField: this.parentField,
 					parentIndex: source.start,
 				};
-				const destinationPath = {
+				const destinationPath: NormalizedUpPath = {
 					parent: this.anchorSet.root,
 					parentField: destination,
 					parentIndex: 0,
+					detachedNodeId,
 				};
 				this.anchorSet.moveChildren(sourcePath, destinationPath, source.end - source.start);
 				this.depthThresholdForSubtreeChanged = this.currentDepth;
@@ -848,9 +872,10 @@ export class AnchorSet implements AnchorLocator {
 				newContentSource: FieldKey,
 				range: Range,
 				oldContentDestination: FieldKey,
+				destinationDetachedNodeId: Delta.DetachedNodeId,
 			): void {
 				this.notifyChildrenChanging();
-				this.detachEdit(range, oldContentDestination);
+				this.detachEdit(range, oldContentDestination, destinationDetachedNodeId);
 				this.attachEdit(newContentSource, range.end - range.start, range.start);
 				this.notifyChildrenChanged();
 			},
@@ -864,7 +889,7 @@ export class AnchorSet implements AnchorLocator {
 					count,
 				);
 			},
-			create(content: Delta.ProtoNodes, destination: FieldKey): void {
+			create(content: ITreeCursorSynchronous[], destination: FieldKey): void {
 				// Nothing to do since content can only be created in a new detached field,
 				// which cannot contain any anchors.
 			},
@@ -969,7 +994,7 @@ enum Status {
  * 2. refcount is non-zero.
  * 3. events are registered.
  */
-class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorNode {
+class PathNode extends ReferenceCountedBase implements AnchorNode {
 	public status: Status = Status.Alive;
 	/**
 	 * Event emitter for this anchor.
@@ -992,6 +1017,11 @@ class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorN
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	public readonly slots: BrandedMapSubset<AnchorSlot<any>> = new Map();
 
+	/**
+	 * {@inheritdoc UpPath.detachedNodeId}
+	 */
+	public detachedNodeId: Delta.DetachedNodeId | undefined;
+
 	/**
 	 * Construct a PathNode with refcount 1.
 	 * @param anchorSet - used to determine if this PathNode is already part of a specific anchorSet

package/src/core/tree/delta.ts

@@ -5,8 +5,7 @@
 
 import type { RevisionTag } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
-
-import type { ITreeCursorSynchronous } from "./cursor.js";
+import type { TreeChunk } from "./chunk.js";
 
 /**
  * This format describes changes that must be applied to a forest in order to update it.
@@ -70,7 +69,7 @@ import type { ITreeCursorSynchronous } from "./cursor.js";
  * Represents the change made to a document.
  * Immutable, therefore safe to retain for async processing.
  */
-export interface Root<TTree = ProtoNode> {
+export interface Root<TTrees = ProtoNodes> {
 	/**
 	 * Changes to apply to the root fields.
 	 */
@@ -83,7 +82,7 @@ export interface Root<TTree = ProtoNode> {
 	 * For example, if one wishes to build a tree which is being renamed from ID A to ID B,
 	 * then the build should be listed under ID A.
 	 */
-	readonly build?: readonly DetachedNodeBuild<TTree>[];
+	readonly build?: readonly DetachedNodeBuild<TTrees>[];
 	/**
 	 * New detached nodes to be destroyed.
 	 * The ordering has no significance.
@@ -97,7 +96,7 @@ export interface Root<TTree = ProtoNode> {
 	 * Refreshers for detached nodes that may need to be recreated.
 	 * The ordering has no significance.
 	 */
-	readonly refreshers?: readonly DetachedNodeBuild<TTree>[];
+	readonly refreshers?: readonly DetachedNodeBuild<TTrees>[];
 	/**
 	 * Changes to apply to detached nodes.
 	 * The ordering has no significance.
@@ -117,25 +116,9 @@ export interface Root<TTree = ProtoNode> {
 }
 
 /**
- * The default representation for inserted content.
- *
- * TODO:
- * Ownership and lifetime of data referenced by this cursor is unclear,
- * so it is a poor abstraction for this use-case which needs to hold onto the data in a non-exclusive (readonly) way.
- * Cursors can be one supported way to input data, but aren't a good storage format.
- */
-export type ProtoNode = ITreeCursorSynchronous;
-
-/**
- * The default representation a chunk (sub-sequence) of inserted content.
- *
- * TODO:
- * See issue TODO with ProtoNode.
- * Additionally, Cursors support sequences, so if using cursors, there are better ways to handle this than an array of cursors,
- * like using a cursor over all the content (starting in fields mode).
- * Long term something like TreeChunk should probably be used here.
+ * The default representation for a chunk (sub-sequence) of inserted content.
  */
-export type ProtoNodes = readonly ProtoNode[];
+export type ProtoNodes = TreeChunk;
 
 /**
  * Represents a change being made to a part of the document tree.
@@ -192,9 +175,9 @@ export interface DetachedNodeChanges {
  * Tree creation is idempotent: if a tree with the same ID already exists,
  * then this build is ignored in favor of the existing tree.
  */
-export interface DetachedNodeBuild<TTree = ProtoNode> {
+export interface DetachedNodeBuild<TTrees = ProtoNodes> {
 	readonly id: DetachedNodeId;
-	readonly trees: readonly TTree[];
+	readonly trees: TTrees;
 }
 
 /**

package/src/core/tree/deltaUtil.ts

@@ -5,12 +5,12 @@
 
 import type { Mutable } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
+import type { TreeChunk } from "./chunk.js";
 
-import type { ITreeCursorSynchronous } from "./cursor.js";
 import type { DetachedNodeId, FieldChanges, Mark, Root } from "./delta.js";
 import { rootFieldKey } from "./types.js";
 
-export const emptyDelta: Root<never> = {};
+export const emptyDelta: Root = {};
 
 export function isAttachMark(mark: Mark): boolean {
 	return mark.attach !== undefined && mark.detach === undefined;
@@ -24,15 +24,15 @@ export function isReplaceMark(mark: Mark): boolean {
 	return mark.detach !== undefined && mark.attach !== undefined;
 }
 
-export function deltaForRootInitialization(content: readonly ITreeCursorSynchronous[]): Root {
-	if (content.length === 0) {
+export function deltaForRootInitialization(content: TreeChunk): Root {
+	if (content.topLevelLength === 0) {
 		return emptyDelta;
 	}
 	const buildId = { minor: 0 };
 	const delta: Root = {
 		build: [{ id: buildId, trees: content }],
 		fields: new Map<FieldKey, FieldChanges>([
-			[rootFieldKey, [{ count: content.length, attach: buildId }]],
+			[rootFieldKey, [{ count: content.topLevelLength, attach: buildId }]],
 		]),
 	};
 	return delta;

package/src/core/tree/index.ts

@@ -33,7 +33,6 @@ export {
 export type {
 	ProtoNodes,
 	Root as DeltaRoot,
-	ProtoNode as DeltaProtoNode,
 	Mark as DeltaMark,
 	DetachedNodeId as DeltaDetachedNodeId,
 	FieldMap as DeltaFieldMap,
@@ -49,6 +48,9 @@ export {
 	topDownPath,
 	getDepth,
 	type UpPath,
+	type NormalizedUpPath,
+	type INormalizedUpPath,
+	type NormalizedFieldUpPath,
 	type FieldUpPath,
 	type Range,
 	type RangeUpPath,
@@ -57,6 +59,7 @@ export {
 	type NodeIndex,
 	compareUpPaths,
 	compareFieldUpPaths,
+	isDetachedUpPathRoot as isDetachedUpPath,
 	getDetachedFieldContainingPath,
 	type UpPathDefault,
 } from "./pathTree.js";

package/src/core/tree/pathTree.ts

@@ -4,6 +4,7 @@
  */
 
 import type { FieldKey } from "../schema-stored/index.js";
+import type { DetachedNodeId } from "./delta.js";
 
 import { type DetachedField, keyAsDetachedField } from "./types.js";
 
@@ -41,12 +42,73 @@ export interface UpPath<TParent = UpPathDefault> {
 	readonly parentIndex: NodeIndex;
 }
 
+/**
+ * Identical to {@link INormalizedUpPath}, but a duplicate declaration is needed to make the default type parameter compile.
+ */
+export type INormalizedUpPathDefault = INormalizedUpPath;
+
+/**
+ * Identical to {@link UpPath}, but a with a {@link DetachedNodeId} to specify the ID of detached roots.
+ * Note that document roots (i.e., any node in the root field) are not considered detached roots and therefore do not have an associated ID.
+ *
+ * Use this interface for implementing a class that needs to be used as a {@link NormalizedUpPath}.
+ */
+export interface INormalizedUpPath<TParent = INormalizedUpPathDefault>
+	extends UpPath<TParent> {
+	readonly detachedNodeId: DetachedNodeId | undefined;
+}
+
+/**
+ * Identical to {@link UpPath}, but a with a {@link DetachedNodeId} to specify the ID of detached roots.
+ * Note that document roots (i.e., any node in the root field) are not considered detached roots and therefore do not have an associated ID.
+ *
+ * Prefer this type over {@link INormalizedUpPath} except when implementing a class that needs to be used as a {@link NormalizedUpPath}.
+ */
+export type NormalizedUpPath =
+	| INormalizedUpPath<NormalizedUpPath>
+	| NormalizedUpPathInterior<NormalizedUpPath>
+	| NormalizedUpPathRoot;
+
+/**
+ * The root element of a {@link NormalizedUpPath}.
+ */
+export interface NormalizedUpPathRoot extends UpPath<undefined> {
+	/**
+	 * The ID associated with this node if it is a detached root.
+	 */
+	readonly detachedNodeId: DetachedNodeId | undefined;
+}
+
+/**
+ * Identical to {@link NormalizedUpPathInterior}, but a duplicate declaration is needed to make the default type parameter compile.
+ */
+export type NormalizedUpPathInteriorDefault = NormalizedUpPathInterior;
+
+/**
+ * An interior (i.e., non-root) element of a {@link NormalizedUpPath}.
+ */
+export interface NormalizedUpPathInterior<
+	TParent = NormalizedUpPathInteriorDefault | NormalizedUpPathRoot,
+> extends UpPath<TParent> {
+	/**
+	 * The parent.
+	 */
+	readonly parent: TParent;
+}
+
 /**
  * Path from a field in the tree upward.
  *
  * See {@link UpPath}.
  */
-export interface FieldUpPath<TUpPath extends UpPath = UpPath> {
+export type NormalizedFieldUpPath<TParent = NormalizedUpPath> = FieldUpPath<TParent>;
+
+/**
+ * Path from a field in the tree upward.
+ *
+ * See {@link FieldUpPath} and {@link NormalizedUpPath}.
+ */
+export interface FieldUpPath<TUpPath = UpPath> {
 	/**
 	 * The parent, or undefined in the case where this path is to a detached sequence.
 	 */
@@ -59,6 +121,15 @@ export interface FieldUpPath<TUpPath extends UpPath = UpPath> {
 	readonly field: FieldKey; // TODO: Type information, including when in DetachedField.
 }
 
+/**
+ * Given an {@link UpPath}, checks if it is a path to a detached root.
+ */
+export function isDetachedUpPathRoot<T>(
+	path: UpPath<T> | NormalizedUpPath,
+): path is NormalizedUpPathRoot {
+	return (path as NormalizedUpPathRoot).detachedNodeId !== undefined;
+}
+
 /**
  * Delimits the extend of a range.
  */

package/src/core/tree/treeTextFormat.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { fail } from "../../util/index.js";
+import { fail } from "@fluidframework/core-utils/internal";
 import type { FieldKey } from "../schema-stored/index.js";
 
 import type { NodeData } from "./types.js";

package/src/core/tree/visitDelta.ts

@@ -8,12 +8,8 @@ import { assert } from "@fluidframework/core-utils/internal";
 import { type NestedMap, setInNestedMap, tryGetFromNestedMap } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
-import type { ITreeCursorSynchronous } from "./cursor.js";
-// eslint-disable-next-line import/no-duplicates
+import { mapCursorField, type ITreeCursorSynchronous } from "./cursor.js";
 import type * as Delta from "./delta.js";
-// Since ProtoNodes is reexported, import it directly to avoid forcing Delta to be reexported.
-// eslint-disable-next-line import/no-duplicates
-import type { ProtoNodes } from "./delta.js";
 import {
 	areDetachedNodeIdsEqual,
 	isAttachMark,
@@ -24,7 +20,7 @@ import {
 import type { DetachedFieldIndex } from "./detachedFieldIndex.js";
 import type { ForestRootId, Major, Minor } from "./detachedFieldIndexTypes.js";
 import type { NodeIndex, PlaceIndex, Range } from "./pathTree.js";
-import type { RevisionTag } from "../index.js";
+import type { RevisionTag, TreeChunk } from "../index.js";
 
 /**
  * Implementation notes:
@@ -59,7 +55,7 @@ import type { RevisionTag } from "../index.js";
  * This needs to happen last to allow modifications to detached roots to be applied before they are destroyed.
  *
  * The details of the delta visit algorithm can impact how/when events are emitted by the objects that own the visitors.
- * For example, as of 2024-03-27, the subtreecChanged event of an AnchorNode is emitted when exiting a node during a
+ * For example, as of 2024-03-27, the subtreeChanged event of an AnchorNode is emitted when exiting a node during a
  * delta visit, and thus the two-pass nature of the algorithm means the event fires twice for any given change.
  * This two-pass nature also means that the event may fire at a time where no change is visible in the tree. E.g.,
  * if a node is being replaced, when the event fires during the detach pass no change in the tree has happened so the
@@ -89,9 +85,10 @@ export function visitDelta(
 	const rootDestructions: Delta.DetachedNodeDestruction[] = [];
 	const refreshers: NestedMap<Major, Minor, ITreeCursorSynchronous> = new Map();
 	delta.refreshers?.forEach(({ id: { major, minor }, trees }) => {
-		for (let i = 0; i < trees.length; i += 1) {
+		const treeCursors = nodeCursorsFromChunk(trees);
+		for (let i = 0; i < trees.topLevelLength; i += 1) {
 			const offsettedId = minor + i;
-			setInNestedMap(refreshers, major, offsettedId, trees[i]);
+			setInNestedMap(refreshers, major, offsettedId, treeCursors[i]);
 		}
 	});
 	const detachConfig: PassConfig = {
@@ -236,7 +233,7 @@ function transferRoots(
 			const oldField = detachedFieldIndex.toFieldKey(oldRootId);
 			const newField = detachedFieldIndex.toFieldKey(newRootId);
 			visitor.enterField(oldField);
-			visitor.detach({ start: 0, end: 1 }, newField);
+			visitor.detach({ start: 0, end: 1 }, newField, newId);
 			visitor.exitField(oldField);
 			detachedFieldIndex.deleteEntry(oldId);
 		}
@@ -266,7 +263,7 @@ export interface DeltaVisitor {
 	 * @param destination - The key for a new detached field.
 	 * A field with this key must not already exist.
 	 */
-	create(content: ProtoNodes, destination: FieldKey): void;
+	create(content: readonly ITreeCursorSynchronous[], destination: FieldKey): void;
 	/**
 	 * Recursively destroys the given detached field and all of the nodes within it.
 	 * @param detachedField - The key for the detached field to destroy.
@@ -287,8 +284,9 @@ export interface DeltaVisitor {
 	 * @param source - The bounds of the range of nodes to detach.
 	 * @param destination - The key for a new detached field.
 	 * A field with this key must not already exist.
+	 * @param id - The ID assigned to the first detached node as a result of the detach. The other nodes in the detached range are assigned subsequent IDs.
 	 */
-	detach(source: Range, destination: FieldKey): void;
+	detach(source: Range, destination: FieldKey, id: Delta.DetachedNodeId): void;
 	/**
 	 * Replaces a range of nodes in the current field by transferring them out to a new detached field
 	 * and transferring in all the nodes from an existing detached field in their place.
@@ -296,8 +294,14 @@ export interface DeltaVisitor {
 	 * @param newContentSource - The detached field to transfer the new nodes from.
 	 * @param range - The bounds of the range of nodes to replace.
 	 * @param oldContentDestination - The key for a new detached field to transfer the old nodes to.
+	 * @param oldContentId - The ID assigned to the first replaced node as a result of the replace. The other nodes in the replaced range are assigned subsequent IDs.
 	 */
-	replace(newContentSource: FieldKey, range: Range, oldContentDestination: FieldKey): void;
+	replace(
+		newContentSource: FieldKey,
+		range: Range,
+		oldContentDestination: FieldKey,
+		oldContentId: Delta.DetachedNodeId,
+	): void;
 
 	/**
 	 * Tells the visitor that it should update its "current location" to be the Node at the specified index
@@ -444,7 +448,7 @@ function detachPass(
 					config.attachPassRoots.set(root, mark.fields);
 				}
 				const field = config.detachedFieldIndex.toFieldKey(root);
-				visitor.detach({ start: index, end: index + 1 }, field);
+				visitor.detach({ start: index, end: index + 1 }, field, id);
 			}
 		} else if (!isAttachMark(mark)) {
 			index += mark.count;
@@ -476,7 +480,13 @@ function processBuilds(
 ): void {
 	if (builds !== undefined) {
 		for (const { id, trees } of builds) {
-			buildTrees(id, trees, config.detachedFieldIndex, config.latestRevision, visitor);
+			buildTrees(
+				id,
+				nodeCursorsFromChunk(trees),
+				config.detachedFieldIndex,
+				config.latestRevision,
+				visitor,
+			);
 		}
 	}
 }
@@ -558,9 +568,10 @@ function attachPass(
 				const sourceField = config.detachedFieldIndex.toFieldKey(sourceRoot);
 				const offsetIndex = index + i;
 				if (isReplaceMark(mark)) {
+					// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+					const destinationId = offsetDetachId(mark.detach!, i);
 					const rootDestination = config.detachedFieldIndex.createEntry(
-						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-						offsetDetachId(mark.detach!, i),
+						destinationId,
 						config.latestRevision,
 					);
 					const destinationField = config.detachedFieldIndex.toFieldKey(rootDestination);
@@ -568,6 +579,7 @@ function attachPass(
 						sourceField,
 						{ start: offsetIndex, end: offsetIndex + 1 },
 						destinationField,
+						destinationId,
 					);
 					// We may need to do a second pass on the detached nodes
 					if (mark.fields !== undefined) {
@@ -592,3 +604,12 @@ function attachPass(
 		}
 	}
 }
+
+/**
+ * Converts a chunk of trees into an array of cursors.
+ *
+ * TODO: Update the visitDelta logic and downstream APIs to avoid splitting up sequences into individual nodes.
+ */
+function nodeCursorsFromChunk(trees: TreeChunk): ITreeCursorSynchronous[] {
+	return mapCursorField(trees.cursor(), (c) => c.fork());
+}

package/src/core/tree/visitorUtils.ts

@@ -10,12 +10,13 @@ import { type IdAllocator, idAllocatorFromMaxId } from "../../util/index.js";
 import type { RevisionTag, RevisionTagCodec } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 
-import type { ProtoNodes, Root } from "./delta.js";
+import type { DetachedNodeId, Root } from "./delta.js";
 import { DetachedFieldIndex } from "./detachedFieldIndex.js";
 import type { ForestRootId } from "./detachedFieldIndexTypes.js";
-import type { NodeIndex, PlaceIndex, Range } from "./pathTree.js";
+import type { PlaceIndex, Range } from "./pathTree.js";
 import { type DeltaVisitor, visitDelta } from "./visitDelta.js";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type { ITreeCursorSynchronous } from "./cursor.js";
 
 export function makeDetachedFieldIndex(
 	prefix: string = "Temp",
@@ -86,21 +87,31 @@ export function combineVisitors(
 			announcedVisitors.forEach((v) => v.beforeAttach(source, count, destination));
 			visitors.forEach((v) => v.attach(source, count, destination));
 			announcedVisitors.forEach((v) =>
-				v.afterAttach(source, { start: destination, end: destination + count }),
+				v.afterAttach(source, {
+					start: destination,
+					end: destination + count,
+				}),
 			);
 		},
-		detach: (source: Range, destination: FieldKey) => {
+		detach: (source: Range, destination: FieldKey, id: DetachedNodeId) => {
 			announcedVisitors.forEach((v) => v.beforeDetach(source, destination));
-			visitors.forEach((v) => v.detach(source, destination));
+			visitors.forEach((v) => v.detach(source, destination, id));
 			announcedVisitors.forEach((v) =>
 				v.afterDetach(source.start, source.end - source.start, destination),
 			);
 		},
-		replace: (newContent: FieldKey, oldContent: Range, oldContentDestination: FieldKey) => {
+		replace: (
+			newContent: FieldKey,
+			oldContent: Range,
+			oldContentDestination: FieldKey,
+			oldContentId: DetachedNodeId,
+		) => {
 			announcedVisitors.forEach((v) =>
 				v.beforeReplace(newContent, oldContent, oldContentDestination),
 			);
-			visitors.forEach((v) => v.replace(newContent, oldContent, oldContentDestination));
+			visitors.forEach((v) =>
+				v.replace(newContent, oldContent, oldContentDestination, oldContentId),
+			);
 			announcedVisitors.forEach((v) =>
 				v.afterReplace(newContent, oldContent, oldContentDestination),
 			);
@@ -120,7 +131,7 @@ export interface AnnouncedVisitor extends DeltaVisitor {
 	/**
 	 * A hook that is called after all nodes have been created.
 	 */
-	afterCreate(content: ProtoNodes, destination: FieldKey): void;
+	afterCreate(content: readonly ITreeCursorSynchronous[], destination: FieldKey): void;
 	beforeDestroy(field: FieldKey, count: number): void;
 	beforeAttach(source: FieldKey, count: number, destination: PlaceIndex): void;
 	afterAttach(source: FieldKey, destination: Range): void;
@@ -138,34 +149,9 @@ export interface AnnouncedVisitor extends DeltaVisitor {
  * Creates an announced visitor with only the provided functions and uses a no op for the rest.
  * This is provided to make some of the delta visitor definitions cleaner.
  */
-export function createAnnouncedVisitor(visitorFunctions: {
-	free?: () => void;
-	create?: (content: ProtoNodes, destination: FieldKey) => void;
-	afterCreate?: (content: ProtoNodes, destination: FieldKey) => void;
-	beforeDestroy?: (field: FieldKey, count: number) => void;
-	destroy?: (detachedField: FieldKey, count: number) => void;
-	beforeAttach?: (source: FieldKey, count: number, destination: PlaceIndex) => void;
-	attach?: (source: FieldKey, count: number, destination: PlaceIndex) => void;
-	afterAttach?: (source: FieldKey, destination: Range) => void;
-	beforeDetach?: (source: Range, destination: FieldKey) => void;
-	afterDetach?: (source: PlaceIndex, count: number, destination: FieldKey) => void;
-	detach?: (source: Range, destination: FieldKey) => void;
-	beforeReplace?: (
-		newContent: FieldKey,
-		oldContent: Range,
-		oldContentDestination: FieldKey,
-	) => void;
-	replace?: (
-		newContentSource: FieldKey,
-		range: Range,
-		oldContentDestination: FieldKey,
-	) => void;
-	afterReplace?: (newContentSource: FieldKey, newContent: Range, oldContent: FieldKey) => void;
-	enterNode?: (index: NodeIndex) => void;
-	exitNode?: (index: NodeIndex) => void;
-	enterField?: (key: FieldKey) => void;
-	exitField?: (key: FieldKey) => void;
-}): AnnouncedVisitor {
+export function createAnnouncedVisitor(
+	visitorFunctions: Partial<AnnouncedVisitor>,
+): AnnouncedVisitor {
 	const noOp = (): void => {};
 	return {
 		free: visitorFunctions.free ?? noOp,

package/src/feature-libraries/chunked-forest/basicChunk.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail } from "@fluidframework/core-utils/internal";
 
 import {
 	CursorLocationType,
@@ -20,7 +20,7 @@ import {
 	cursorChunk,
 	dummyRoot,
 } from "../../core/index.js";
-import { ReferenceCountedBase, fail } from "../../util/index.js";
+import { ReferenceCountedBase } from "../../util/index.js";
 import { SynchronousCursor, prefixPath } from "../treeCursorUtils.js";
 
 /**
@@ -84,7 +84,7 @@ export type SiblingsOrKey = readonly TreeChunk[] | readonly FieldKey[];
  * Cursor over basic chunks.
  *
  * @remarks This implementation is similar to StackCursor, however it is distinct because:
- * 1. The children are chunks, which might have a top level length that greater than 1.
+ * 1. The children are chunks, which might have a top level length that's greater than 1.
  * 2. It needs to be able to delegate to cursors of other chunk formats it does not natively understand (See TODO below).
  *
  * TODO: