@fluidframework/tree 2.23.0 → 2.30.0

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

@@ -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:

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert, oob } from "@fluidframework/core-utils/internal";
 
 import {
 	CursorLocationType,
@@ -30,7 +30,7 @@ import type { FullSchemaPolicy } from "../modular-schema/index.js";
 import { BasicChunk } from "./basicChunk.js";
 import { SequenceChunk } from "./sequenceChunk.js";
 import { type FieldShape, TreeShape, UniformChunk } from "./uniformChunk.js";
-import { isStableNodeKey } from "../node-key/index.js";
+import { isStableNodeIdentifier } from "../node-identifier/index.js";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 export interface Disposable {
@@ -175,7 +175,9 @@ export function chunkField(
 ): TreeChunk[] {
 	const length = cursor.getFieldLength();
 	const started = cursor.firstNode();
-	assert(started, 0x57c /* field to chunk should have at least one node */);
+	debugAssert(
+		() => started === (length !== 0) || "only 0 length fields should not have nodes",
+	);
 	return chunkRange(cursor, policy, length, false);
 }
 
@@ -373,10 +375,12 @@ function newBasicChunkTree(
 }
 
 /**
- * @param cursor - cursor in nodes mode
+ * Chunk a portion of a field.
+ *
+ * @param cursor - cursor at the starting node in the field.
  * @param policy - heuristics to impact chunking
- * @param length - how many nodes to process (at the top level)
- * @param skipLastNavigation - if true, leaves the cursor at the last node instead of moving off of it.
+ * @param length - how many nodes to process (at the top level). When 0, the cursor is not moved, and may be at the end of the field (and thus in Fields mode)
+ * @param skipLastNavigation - if true, leaves the cursor at the last node instead of moving off of it. Invalid if length is 0.
  */
 export function chunkRange(
 	cursor: ITreeCursorSynchronous,
@@ -384,7 +388,14 @@ export function chunkRange(
 	length: number,
 	skipLastNavigation: boolean,
 ): TreeChunk[] {
-	assert(cursor.mode === CursorLocationType.Nodes, 0x57e /* should be in nodes */);
+	assert(
+		!(skipLastNavigation && length === 0),
+		0xb58 /* Cannot skip last navigation if length is 0 and thus last navigation already occurred. */,
+	);
+	assert(
+		(cursor.mode === CursorLocationType.Nodes) === length > 0,
+		0xb59 /* Should be in nodes mode if not past end */,
+	);
 	let output: TreeChunk[] = [];
 	let remaining = length;
 	while (remaining > 0) {
@@ -498,7 +509,7 @@ export function insertValues(
 		if (
 			typeof cursor.value === "string" &&
 			idCompressor !== undefined &&
-			isStableNodeKey(cursor.value)
+			isStableNodeIdentifier(cursor.value)
 		) {
 			values.push(idCompressor.tryRecompress(cursor.value) ?? cursor.value);
 		} else {

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

@@ -21,7 +21,6 @@ import {
 	type ITreeSubscriptionCursor,
 	ITreeSubscriptionCursorState,
 	type PlaceIndex,
-	type ProtoNodes,
 	type Range,
 	TreeNavigationResult,
 	type TreeStoredSchemaSubscription,
@@ -33,6 +32,7 @@ import {
 	rootFieldKey,
 	type ChunkedCursor,
 	type TreeChunk,
+	type DeltaDetachedNodeId,
 } from "../../core/index.js";
 import {
 	assertValidRange,
@@ -44,7 +44,7 @@ import {
 } from "../../util/index.js";
 
 import { BasicChunk, BasicChunkCursor, type SiblingsOrKey } from "./basicChunk.js";
-import { type IChunker, basicChunkTree, chunkTree } from "./chunkTree.js";
+import { type IChunker, basicChunkTree, chunkFieldSingle, chunkTree } from "./chunkTree.js";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 function makeRoot(): BasicChunk {
@@ -91,6 +91,10 @@ export class ChunkedForest implements IEditableForest {
 		return new ChunkedForest(this.roots, schema, this.chunker.clone(schema), anchors);
 	}
 
+	public chunkField(cursor: ITreeCursorSynchronous): TreeChunk {
+		return chunkFieldSingle(cursor, { idCompressor: this.idCompressor, policy: this.chunker });
+	}
+
 	public forgetAnchor(anchor: Anchor): void {
 		this.anchors.forget(anchor);
 	}
@@ -136,7 +140,7 @@ export class ChunkedForest implements IEditableForest {
 				this.forest.#events.emit("beforeChange");
 				this.forest.roots.fields.delete(detachedField);
 			},
-			create(content: ProtoNodes, destination: FieldKey): void {
+			create(content: readonly ITreeCursorSynchronous[], destination: FieldKey): void {
 				this.forest.#events.emit("beforeChange");
 				const chunks: TreeChunk[] = content.map((c) =>
 					chunkTree(c, {
@@ -150,7 +154,7 @@ export class ChunkedForest implements IEditableForest {
 			attach(source: FieldKey, count: number, destination: PlaceIndex): void {
 				this.attachEdit(source, count, destination);
 			},
-			detach(source: Range, destination: FieldKey): void {
+			detach(source: Range, destination: FieldKey, id: DeltaDetachedNodeId): void {
 				this.detachEdit(source, destination);
 			},
 			/**
@@ -210,6 +214,7 @@ export class ChunkedForest implements IEditableForest {
 				newContentSource: FieldKey,
 				range: Range,
 				oldContentDestination: FieldKey,
+				oldContentId: DeltaDetachedNodeId,
 			): void {
 				assert(
 					newContentSource !== oldContentDestination,

package/src/feature-libraries/chunked-forest/codec/README.md

@@ -8,8 +8,8 @@ Two main algorithms are used:
 
 -   Shape based encoding: Trees are split into "Shape" information and "Data".
     "Shape" can (but does not have to) contain information like type, which fields exist, and how many nodes are in them and the shapes of those nodes.
--   [Dictionary Coding](https://go-compression.github.io/algorithms/dictionary/) using `Counter` from [chunkCodexUtilities.ts](./chunkCodecUtilities.ts)
-    is applied to Identifiers (such a type names and field keys) and Shapes.
+-   [Dictionary Coding](https://go-compression.github.io/algorithms/dictionary/) using `Counter` from [chunkCodecUtilities.ts](./chunkCodecUtilities.ts)
+    is applied to Identifiers (such as type names and field keys) and Shapes.
 
 The main challenge is deciding what shapes to use: if too much information is captured in the shape, there will be more shapes which take up more space,
 but if too little information is captured in the shapes, the size of the encoded tree will be large.
@@ -20,7 +20,7 @@ A few implementations are included which make different choices here:
 -   [uncompressedEncode.ts](uncompressedEncode.ts): the simplest implementation, which captures nothing in the shape and does no Dictionary Coding of identifiers.
     This makes for more human readable data as well as a simple reference implementation.
 -   [compressedEncode.ts](compressedEncode.ts): some utilities for actual compressed encoding, but does not contain any advanced strategies (instead they must be provided to it via the `EncoderCache`)
--   [schemaBasedEncoding.ts](schemaBasedEncoding.ts): a strategy for compressedEncode using schema to infer commonly used shapes.
+-   [schemaBasedEncode.ts](schemaBasedEncode.ts): a strategy for compressedEncode using schema to infer commonly used shapes.
 
 ### Future Optimizations
 

package/src/feature-libraries/chunked-forest/codec/codecs.ts

@@ -17,7 +17,7 @@ import { TreeCompressionStrategy } from "../../treeCompressionUtils.js";
 import { decode } from "./chunkDecoding.js";
 import type { FieldBatch } from "./fieldBatch.js";
 import { EncodedFieldBatch, validVersions } from "./format.js";
-import { schemaCompressedEncode } from "./schemaBasedEncoding.js";
+import { schemaCompressedEncode } from "./schemaBasedEncode.js";
 import { uncompressedEncode } from "./uncompressedEncode.js";
 import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
 

package/src/feature-libraries/chunked-forest/codec/compressedEncode.ts

@@ -37,7 +37,7 @@ import {
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
 /**
- * Encode data from `FieldBatch` in into an `EncodedChunk`.
+ * Encode data from `FieldBatch` into an `EncodedChunk`.
  *
  * Optimized for encoded size and encoding performance.
  *

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

@@ -233,9 +233,10 @@ class OffsetShape {
 	/**
 	 * @param shape - the shape of each child in this field
 	 * @param topLevelLength - number of top level nodes in this sequence chunk (either field within a chunk, or top level chunk)
-	 * @param offset - number of nodes before this in the parent's subtree
+	 * @param offset - number of nodes before this in the parent's subtree. The nodes are considered in depth first pre order
+	 * traversal, so a parent is the first node in its subtree (before its children) with offset 0
 	 * @param key - field key
-	 * @param indexOfParentField - index of node with this shape
+	 * @param indexOfParentField - index to this shape in the parent's array of fields
 	 */
 	public constructor(
 		public readonly shape: TreeShape,

package/src/feature-libraries/default-schema/defaultEditBuilder.ts

@@ -13,13 +13,14 @@ import {
 	type ChangeFamily,
 	type ChangeFamilyEditor,
 	type ChangeRebaser,
-	CursorLocationType,
 	type DeltaDetachedNodeId,
 	type DeltaRoot,
 	type FieldUpPath,
-	type ITreeCursorSynchronous,
+	type NormalizedFieldUpPath,
+	type NormalizedUpPath,
 	type RevisionTag,
 	type TaggedChange,
+	type TreeChunk,
 	type UpPath,
 	compareFieldUpPaths,
 	topDownPath,
@@ -43,7 +44,6 @@ import {
 	sequence,
 	required as valueFieldKind,
 } from "./defaultFieldKinds.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
 import type { CellId } from "../sequence-field/index.js";
 
 export type DefaultChangeset = ModularChangeset;
@@ -120,14 +120,14 @@ export function relevantRemovedRoots(change: ModularChangeset): Iterable<DeltaDe
  * If/when such a mechanism becomes available, an evaluation should be done to determine if any existing editing operations should be changed to leverage it
  * (Possibly by adding opt ins at the view schema layer).
  */
-export interface IDefaultEditBuilder {
+export interface IDefaultEditBuilder<TContent = TreeChunk> {
 	/**
 	 * @param field - the value field which is being edited under the parent node
 	 * @returns An object with methods to edit the given field of the given parent.
 	 * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
 	 * is bounded by the lifetime of this edit builder.
 	 */
-	valueField(field: FieldUpPath): ValueFieldEditBuilder<ITreeCursorSynchronous>;
+	valueField(field: NormalizedFieldUpPath): ValueFieldEditBuilder<TContent>;
 
 	/**
 	 * @param field - the optional field which is being edited under the parent node
@@ -135,7 +135,7 @@ export interface IDefaultEditBuilder {
 	 * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
 	 * is bounded by the lifetime of this edit builder.
 	 */
-	optionalField(field: FieldUpPath): OptionalFieldEditBuilder<ITreeCursorSynchronous>;
+	optionalField(field: NormalizedFieldUpPath): OptionalFieldEditBuilder<TContent>;
 
 	/**
 	 * @param field - the sequence field which is being edited under the parent node
@@ -144,7 +144,7 @@ export interface IDefaultEditBuilder {
 	 * The returned object can be used (i.e., have its methods called) multiple times but its lifetime
 	 * is bounded by the lifetime of this edit builder.
 	 */
-	sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<ITreeCursorSynchronous>;
+	sequenceField(field: NormalizedFieldUpPath): SequenceFieldEditBuilder<TContent>;
 
 	/**
 	 * Moves a subsequence from one sequence field to another sequence field.
@@ -153,10 +153,10 @@ export interface IDefaultEditBuilder {
 	 * For example, `move(field, 0, 1, field, 2)` changes `[A, B, C]` to `[B, A, C]`.
 	 */
 	move(
-		sourceField: FieldUpPath,
+		sourceField: NormalizedFieldUpPath,
 		sourceIndex: number,
 		count: number,
-		destinationField: FieldUpPath,
+		destinationField: NormalizedFieldUpPath,
 		destinationIndex: number,
 	): void;
 
@@ -164,13 +164,13 @@ export interface IDefaultEditBuilder {
 	 * Add a constraint that the node at the given path must exist.
 	 * @param path - The path to the node that must exist.
 	 */
-	addNodeExistsConstraint(path: UpPath): void;
+	addNodeExistsConstraint(path: NormalizedUpPath): void;
 
 	/**
 	 * Add a constraint that the node at the given path must exist when reverting a change.
 	 * @param path - The path to the node that must exist when reverting a change.
 	 */
-	addNodeExistsConstraintOnRevert(path: UpPath): void;
+	addNodeExistsConstraintOnRevert(path: NormalizedUpPath): void;
 }
 
 /**
@@ -184,7 +184,6 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		family: ChangeFamily<ChangeFamilyEditor, DefaultChangeset>,
 		private readonly mintRevisionTag: () => RevisionTag,
 		changeReceiver: (change: TaggedChange<DefaultChangeset>) => void,
-		private readonly idCompressor?: IIdCompressor,
 	) {
 		this.modularBuilder = new ModularEditBuilder(family, fieldKinds, changeReceiver);
 	}
@@ -204,18 +203,13 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		this.modularBuilder.addNodeExistsConstraintOnRevert(path, this.mintRevisionTag());
 	}
 
-	public valueField(field: FieldUpPath): ValueFieldEditBuilder<ITreeCursorSynchronous> {
+	public valueField(field: FieldUpPath): ValueFieldEditBuilder<TreeChunk> {
 		return {
-			set: (newContent: ITreeCursorSynchronous): void => {
+			set: (newContent: TreeChunk): void => {
 				const revision = this.mintRevisionTag();
 				const fill: ChangeAtomId = { localId: this.modularBuilder.generateId(), revision };
 				const detach: ChangeAtomId = { localId: this.modularBuilder.generateId(), revision };
-				const build = this.modularBuilder.buildTrees(
-					fill.localId,
-					newContent,
-					revision,
-					this.idCompressor,
-				);
+				const build = this.modularBuilder.buildTrees(fill.localId, newContent, revision);
 				const change: FieldChangeset = brand(
 					valueFieldKind.changeHandler.editor.set({
 						fill,
@@ -235,21 +229,16 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		};
 	}
 
-	public optionalField(field: FieldUpPath): OptionalFieldEditBuilder<ITreeCursorSynchronous> {
+	public optionalField(field: FieldUpPath): OptionalFieldEditBuilder<TreeChunk> {
 		return {
-			set: (newContent: ITreeCursorSynchronous | undefined, wasEmpty: boolean): void => {
+			set: (newContent: TreeChunk | undefined, wasEmpty: boolean): void => {
 				const edits: EditDescription[] = [];
 				let optionalChange: OptionalChangeset;
 				const revision = this.mintRevisionTag();
 				const detach: ChangeAtomId = { localId: this.modularBuilder.generateId(), revision };
 				if (newContent !== undefined) {
 					const fill: ChangeAtomId = { localId: this.modularBuilder.generateId(), revision };
-					const build = this.modularBuilder.buildTrees(
-						fill.localId,
-						newContent,
-						revision,
-						this.idCompressor,
-					);
+					const build = this.modularBuilder.buildTrees(fill.localId, newContent, revision);
 					edits.push(build);
 
 					optionalChange = optional.changeHandler.editor.set(wasEmpty, {
@@ -381,23 +370,17 @@ export class DefaultEditBuilder implements ChangeFamilyEditor, IDefaultEditBuild
 		}
 	}
 
-	public sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<ITreeCursorSynchronous> {
+	public sequenceField(field: FieldUpPath): SequenceFieldEditBuilder<TreeChunk> {
 		return {
-			insert: (index: number, content: ITreeCursorSynchronous): void => {
-				const length =
-					content.mode === CursorLocationType.Fields ? content.getFieldLength() : 1;
+			insert: (index: number, content: TreeChunk): void => {
+				const length = content.topLevelLength;
 				if (length === 0) {
 					return;
 				}
 
 				const revision = this.mintRevisionTag();
 				const firstId: CellId = { localId: this.modularBuilder.generateId(length), revision };
-				const build = this.modularBuilder.buildTrees(
-					firstId.localId,
-					content,
-					revision,
-					this.idCompressor,
-				);
+				const build = this.modularBuilder.buildTrees(firstId.localId, content, revision);
 				const change: FieldChangeset = brand(
 					sequence.changeHandler.editor.insert(index, length, firstId, revision),
 				);

package/src/feature-libraries/default-schema/index.ts

@@ -29,3 +29,5 @@ export {
 export { SchemaValidationErrors, isNodeInSchema, isFieldInSchema } from "./schemaChecker.js";
 
 export { defaultSchemaPolicy } from "./defaultSchema.js";
+
+export { MappedEditBuilder } from "./mappedEditBuilder.js";