@fluidframework/tree 2.13.0 → 2.21.0

package/src/feature-libraries/optional-field/optionalField.ts

@@ -11,7 +11,6 @@ import {
 	type ChangesetLocalId,
 	type DeltaDetachedNodeChanges,
 	type DeltaDetachedNodeId,
-	type DeltaFieldChanges,
 	type DeltaMark,
 	type RevisionTag,
 	areEqualChangeAtomIds,
@@ -40,6 +39,7 @@ import {
 	type RelevantRemovedRootsFromChild,
 	type ToDelta,
 	type NestedChangesIndices,
+	type FieldChangeDelta,
 } from "../modular-schema/index.js";
 
 import type {
@@ -657,8 +657,8 @@ export const optionalFieldEditor: OptionalFieldEditor = {
 export function optionalFieldIntoDelta(
 	change: OptionalChangeset,
 	deltaFromChild: ToDelta,
-): DeltaFieldChanges {
-	const delta: Mutable<DeltaFieldChanges> = {};
+): FieldChangeDelta {
+	const delta: Mutable<FieldChangeDelta> = {};
 
 	let markIsANoop = true;
 	const mark: Mutable<DeltaMark> = { count: 1 };

package/src/feature-libraries/sequence-field/moveEffectTable.ts

@@ -101,7 +101,7 @@ export function getMoveEffect(
 	id: MoveId,
 	count: number,
 	addDependency: boolean = true,
-): RangeQueryResult<MoveEffect> {
+): RangeQueryResult<ChangeAtomId, MoveEffect> {
 	const result = moveEffects.get(target, revision, id, count, addDependency);
 	return result.value !== undefined
 		? { ...result, value: adjustMoveEffectBasis(result.value as MoveEffectWithBasis, id) }

package/src/feature-libraries/sequence-field/rebase.ts

@@ -545,9 +545,14 @@ function getMovedChangesFromBaseMark(
 	baseMark: Mark,
 ): NodeId | undefined {
 	if (isMoveIn(baseMark)) {
-		return getMovedNodeChanges(moveEffects, baseMark.revision, baseMark.id);
+		return getMovedNodeChanges(moveEffects, baseMark.revision, baseMark.id, baseMark.count);
 	} else if (isAttachAndDetachEffect(baseMark) && isMoveIn(baseMark.attach)) {
-		return getMovedNodeChanges(moveEffects, baseMark.attach.revision, baseMark.attach.id);
+		return getMovedNodeChanges(
+			moveEffects,
+			baseMark.attach.revision,
+			baseMark.attach.id,
+			baseMark.count,
+		);
 	} else {
 		return undefined;
 	}
@@ -557,7 +562,8 @@ function getMovedNodeChanges(
 	moveEffects: MoveEffectTable,
 	revision: RevisionTag | undefined,
 	id: MoveId,
+	count: number,
 ): NodeId | undefined {
-	return getMoveEffect(moveEffects, CrossFieldTarget.Destination, revision, id, 1).value
+	return getMoveEffect(moveEffects, CrossFieldTarget.Destination, revision, id, count).value
 		?.rebasedChanges;
 }

package/src/feature-libraries/sequence-field/sequenceFieldCodecV1.ts

@@ -145,7 +145,7 @@ export function makeV1Codec(
 						context,
 					);
 				case NoopMarkType:
-					fail(`Mark type: ${type} should not be encoded.`);
+					fail("Mark type: NoopMarkType should not be encoded.");
 				default:
 					unreachableCase(type);
 			}

package/src/feature-libraries/sequence-field/sequenceFieldCodecV2.ts

@@ -132,7 +132,7 @@ export function makeV2CodecHelpers(
 						context,
 					);
 				case NoopMarkType:
-					fail(`Mark type: ${type} should not be encoded.`);
+					fail("Mark type: NoopMarkType should not be encoded.");
 				default:
 					unreachableCase(type);
 			}

package/src/feature-libraries/sequence-field/sequenceFieldToDelta.ts

@@ -8,7 +8,6 @@ import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import {
 	type DeltaDetachedNodeChanges,
 	type DeltaDetachedNodeRename,
-	type DeltaFieldChanges,
 	type DeltaMark,
 	areEqualChangeAtomIds,
 } from "../../core/index.js";
@@ -25,12 +24,12 @@ import {
 	getInputCellId,
 	isAttachAndDetachEffect,
 } from "./utils.js";
-import type { ToDelta } from "../modular-schema/index.js";
+import type { FieldChangeDelta, ToDelta } from "../modular-schema/index.js";
 
 export function sequenceFieldToDelta(
 	change: MarkList,
 	deltaFromChild: ToDelta,
-): DeltaFieldChanges {
+): FieldChangeDelta {
 	const local: DeltaMark[] = [];
 	const global: DeltaDetachedNodeChanges[] = [];
 	const rename: DeltaDetachedNodeRename[] = [];
@@ -187,7 +186,7 @@ export function sequenceFieldToDelta(
 		}
 		local.pop();
 	}
-	const delta: Mutable<DeltaFieldChanges> = {};
+	const delta: Mutable<FieldChangeDelta> = {};
 	if (local.length > 0) {
 		delta.local = local;
 	}

package/src/feature-libraries/sequence-field/utils.ts

@@ -942,13 +942,45 @@ function getCrossFieldKeysForMarkEffect(
 			// An insert behaves like a move where the source and destination are at the same location.
 			// An insert can become a move when after rebasing.
 			return [
-				[CrossFieldTarget.Source, effect.revision, effect.id, count],
-				[CrossFieldTarget.Destination, effect.revision, effect.id, count],
+				{
+					key: {
+						target: CrossFieldTarget.Source,
+						revision: effect.revision,
+						localId: effect.id,
+					},
+					count,
+				},
+				{
+					key: {
+						target: CrossFieldTarget.Destination,
+						revision: effect.revision,
+						localId: effect.id,
+					},
+					count,
+				},
 			];
 		case "MoveOut":
-			return [[CrossFieldTarget.Source, effect.revision, effect.id, count]];
+			return [
+				{
+					key: {
+						target: CrossFieldTarget.Source,
+						revision: effect.revision,
+						localId: effect.id,
+					},
+					count,
+				},
+			];
 		case "MoveIn":
-			return [[CrossFieldTarget.Destination, effect.revision, effect.id, count]];
+			return [
+				{
+					key: {
+						target: CrossFieldTarget.Destination,
+						revision: effect.revision,
+						localId: effect.id,
+					},
+					count,
+				},
+			];
 		case "AttachAndDetach":
 			return [
 				...getCrossFieldKeysForMarkEffect(effect.attach, count),

package/src/feature-libraries/treeCursorUtils.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert, oob, debugAssert } from "@fluidframework/core-utils/internal";
 
 import {
 	CursorLocationType,
@@ -20,6 +20,7 @@ import {
 	rootField,
 } from "../core/index.js";
 import { fail } from "../util/index.js";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * {@link ITreeCursorSynchronous} that can return the underlying node objects.
@@ -146,7 +147,9 @@ class StackCursor<TNode> extends SynchronousCursor implements CursorWithNode<TNo
 	}
 
 	public getFieldKey(): FieldKey {
-		// assert(this.mode === CursorLocationType.Fields, "must be in fields mode");
+		debugAssert(() =>
+			this.mode === CursorLocationType.Fields ? true : "must be in fields mode",
+		);
 		return this.siblings[this.index] as FieldKey;
 	}
 
@@ -177,7 +180,11 @@ class StackCursor<TNode> extends SynchronousCursor implements CursorWithNode<TNo
 	public enterNode(index: number): void {
 		// assert(this.mode === CursorLocationType.Fields, "must be in fields mode");
 		const siblings = this.getField();
-		assert(index in siblings, 0x405 /* child must exist at index */);
+		if (!(index in siblings)) {
+			throw new UsageError(
+				"A child does not exist at the specified index, check the status of a node using `Tree.status()`.",
+			);
+		}
 		this.siblingStack.push(this.siblings);
 		this.indexStack.push(this.index);
 		this.index = index;

package/src/index.ts

@@ -14,13 +14,38 @@ export {
 	type RevertibleAlpha,
 } from "./core/index.js";
 
-export type {
-	Listeners,
-	IsListener,
-	Listenable,
-	Off,
+import type {
+	Listeners as EventListeners,
+	IsListener as EventIsListener,
+	Listenable as EventListenable,
+	Off as EventOff,
 } from "@fluidframework/core-interfaces";
 
+/**
+ * {@inheritdoc @fluidframework/core-interfaces#Listeners}
+ * @public
+ * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
+ */
+export type Listeners<T extends object> = EventListeners<T>;
+/**
+ * {@inheritdoc @fluidframework/core-interfaces#IsListener}
+ * @public
+ * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
+ */
+export type IsListener<T> = EventIsListener<T>;
+/**
+ * {@inheritdoc @fluidframework/core-interfaces#Listenable}
+ * @public
+ * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
+ */
+export type Listenable<T extends object> = EventListenable<T>;
+/**
+ * {@inheritdoc @fluidframework/core-interfaces#Off}
+ * @public
+ * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
+ */
+export type Off = EventOff;
+
 export {
 	TreeStatus,
 	TreeCompressionStrategy,
@@ -32,7 +57,7 @@ export {
 export {
 	type ITreeInternal,
 	type SharedTreeOptions,
-	ForestType,
+	type ForestType,
 	type SharedTreeFormatOptions,
 	SharedTreeFormatVersion,
 	Tree,
@@ -55,6 +80,11 @@ export {
 	type TransactionResultExt,
 	type TransactionResultSuccess,
 	type TransactionResultFailed,
+	ForestTypeOptimized,
+	ForestTypeExpensiveDebug,
+	ForestTypeReference,
+	SharedTreeAttributes,
+	SharedTreeFactoryType,
 } from "./shared-tree/index.js";
 
 export {

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.13.0";
+export const pkgVersion = "2.21.0";

package/src/shared-tree/index.ts

@@ -9,7 +9,7 @@ export {
 	type SharedTreeOptions,
 	SharedTree,
 	getBranch,
-	ForestType,
+	type ForestType,
 	type SharedTreeContentSnapshot,
 	type SharedTreeFormatOptions,
 	SharedTreeFormatVersion,
@@ -17,8 +17,16 @@ export {
 	defaultSharedTreeOptions,
 	type ForestOptions,
 	type ITreeInternal,
+	ForestTypeOptimized,
+	ForestTypeExpensiveDebug,
+	ForestTypeReference,
 } from "./sharedTree.js";
 
+export {
+	SharedTreeAttributes,
+	SharedTreeFactoryType,
+} from "./publicContracts.js";
+
 export {
 	createTreeCheckout,
 	TreeCheckout,

package/src/shared-tree/publicContracts.ts

@@ -0,0 +1,24 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IChannelAttributes } from "@fluidframework/datastore-definitions/internal";
+
+/**
+ * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
+ * @alpha
+ * @legacy
+ */
+export const SharedTreeFactoryType = "https://graph.microsoft.com/types/tree";
+
+/**
+ * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory.attributes}
+ * @alpha
+ * @legacy
+ */
+export const SharedTreeAttributes: IChannelAttributes = {
+	type: SharedTreeFactoryType,
+	snapshotFormatVersion: "0.0.0",
+	packageVersion: "0.0.0",
+};

package/src/shared-tree/sharedTree.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
-import type { IFluidHandle } from "@fluidframework/core-interfaces/internal";
+import { assert } from "@fluidframework/core-utils/internal";
+import type { ErasedType, IFluidHandle } from "@fluidframework/core-interfaces/internal";
 import type {
 	IChannelAttributes,
 	IChannelFactory,
@@ -84,6 +84,7 @@ import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { type TreeCheckout, type BranchableTree, createTreeCheckout } from "./treeCheckout.js";
 import { breakingClass, fail, throwIfBroken } from "../util/index.js";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
+import { SharedTreeAttributes, SharedTreeFactoryType } from "./publicContracts.js";
 
 /**
  * Copy of data from an {@link ISharedTree} at some point in time.
@@ -186,30 +187,6 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 	return versions;
 }
 
-/**
- * Build and return a forest of the requested type.
- */
-export function buildConfiguredForest(
-	type: ForestType,
-	schema: TreeStoredSchemaSubscription,
-	idCompressor: IIdCompressor,
-): IEditableForest {
-	switch (type) {
-		case ForestType.Optimized:
-			return buildChunkedForest(
-				makeTreeChunker(schema, defaultSchemaPolicy),
-				undefined,
-				idCompressor,
-			);
-		case ForestType.Reference:
-			return buildForest();
-		case ForestType.Expensive:
-			return buildForest(undefined, true);
-		default:
-			unreachableCase(type);
-	}
-}
-
 /**
  * Shared tree, configured with a good set of indexes and field kinds which will maintain compatibility over time.
  *
@@ -596,26 +573,70 @@ export interface SharedTreeFormatOptions {
 
 /**
  * Used to distinguish between different forest types.
+ * @remarks
+ * Current options are {@link ForestTypeReference}, {@link ForestTypeOptimized} and {@link ForestTypeExpensiveDebug}.
+ * @sealed @alpha
+ */
+export interface ForestType extends ErasedType<"ForestType"> {}
+
+/**
+ * Reference implementation of forest.
+ * @remarks
+ * A simple implementation with minimal complexity and moderate debuggability, validation and performance.
+ * @privateRemarks
+ * The "ObjectForest" forest type.
  * @alpha
  */
-export enum ForestType {
-	/**
-	 * The "ObjectForest" forest type.
-	 */
-	Reference = 0,
-	/**
-	 * The "ChunkedForest" forest type.
-	 */
-	Optimized = 1,
-	/**
-	 * The "ObjectForest" forest type with expensive asserts for debugging.
-	 */
-	Expensive = 2,
+export const ForestTypeReference = toForestType(() => buildForest());
+
+/**
+ * Optimized implementation of forest.
+ * @remarks
+ * A complex optimized forest implementation, which has minimal validation and debuggability to optimize for performance.
+ * Uses an internal representation optimized for size designed to scale to larger datasets with reduced overhead.
+ * @privateRemarks
+ * The "ChunkedForest" forest type.
+ * @alpha
+ */
+export const ForestTypeOptimized = toForestType(
+	(schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
+		buildChunkedForest(makeTreeChunker(schema, defaultSchemaPolicy), undefined, idCompressor),
+);
+
+/**
+ * Slow implementation of forest intended only for debugging.
+ * @remarks
+ * Includes validation with scales poorly.
+ * May be asymptotically slower than {@link ForestTypeReference}, and may perform very badly with larger data sizes.
+ * @privateRemarks
+ * The "ObjectForest" forest type with expensive asserts for debugging.
+ * @alpha
+ */
+export const ForestTypeExpensiveDebug = toForestType(() => buildForest(undefined, true));
+
+type ForestFactory = (
+	schema: TreeStoredSchemaSubscription,
+	idCompressor: IIdCompressor,
+) => IEditableForest;
+
+function toForestType(factory: ForestFactory): ForestType {
+	return factory as unknown as ForestType;
+}
+
+/**
+ * Build and return a forest of the requested type.
+ */
+export function buildConfiguredForest(
+	factory: ForestType,
+	schema: TreeStoredSchemaSubscription,
+	idCompressor: IIdCompressor,
+): IEditableForest {
+	return (factory as unknown as ForestFactory)(schema, idCompressor);
 }
 
 export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	jsonValidator: noopValidator,
-	forest: ForestType.Reference,
+	forest: ForestTypeReference,
 	treeEncodeType: TreeCompressionStrategy.Compressed,
 	formatVersion: SharedTreeFormatVersion.v3,
 	disposeForksAfterTransaction: true,
@@ -625,13 +646,9 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
  * A channel factory that creates {@link ISharedTree}s.
  */
 export class SharedTreeFactory implements IChannelFactory<ISharedTree> {
-	public readonly type: string = "https://graph.microsoft.com/types/tree";
+	public readonly type: string = SharedTreeFactoryType;
 
-	public readonly attributes: IChannelAttributes = {
-		type: this.type,
-		snapshotFormatVersion: "0.0.0",
-		packageVersion: "0.0.0",
-	};
+	public readonly attributes: IChannelAttributes = SharedTreeAttributes;
 
 	public constructor(private readonly options: SharedTreeOptionsInternal = {}) {}
 

package/src/shared-tree/treeCheckout.ts

@@ -41,6 +41,7 @@ import {
 	type RevertibleAlphaFactory,
 	type RevertibleAlpha,
 	type GraphCommit,
+	isAncestor,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -605,21 +606,27 @@ export class TreeCheckout implements ITreeCheckoutFork {
 					revertible.dispose();
 				}
 			},
-			clone: (forkedBranch: TreeBranch) => {
-				if (forkedBranch === undefined) {
-					return this.createRevertible(revision, kind, checkout, onRevertibleDisposed);
-				}
-
+			clone: (targetBranch: TreeBranch) => {
 				// TODO:#23442: When a revertible is cloned for a forked branch, optimize to create a fork of a revertible branch once per revision NOT once per revision per checkout.
-				const forkedCheckout = getCheckout(forkedBranch);
+				const targetCheckout = getCheckout(targetBranch);
+
 				const revertibleBranch = this.revertibleCommitBranches.get(revision);
-				assert(
-					revertibleBranch !== undefined,
-					0xa82 /* change to revert does not exist on the given forked branch */,
-				);
-				forkedCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
+				if (revertibleBranch === undefined) {
+					throw new UsageError("Unable to clone a revertible that has been disposed.");
+				}
+
+				const commitToRevert = revertibleBranch.getHead();
+				const activeBranchHead = targetCheckout.#transaction.activeBranch.getHead();
+
+				if (isAncestor(commitToRevert, activeBranchHead, true) === false) {
+					throw new UsageError(
+						"Cannot clone revertible for a commit that is not present on the given branch.",
+					);
+				}
+
+				targetCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
 
-				return this.createRevertible(revision, kind, forkedCheckout, onRevertibleDisposed);
+				return this.createRevertible(revision, kind, targetCheckout, onRevertibleDisposed);
 			},
 			dispose: () => {
 				if (revertible.status === RevertibleStatus.Disposed) {

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

@@ -263,6 +263,8 @@ export type ScopedSchemaName<
  *
  * Note: the comparison between the customizable and POJO modes is not done in a table because TSDoc does not currently have support for embedded markdown.
  *
+ * @see {@link SchemaFactoryAlpha}
+ *
  * @sealed @public
  */
 export class SchemaFactory<

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

@@ -467,6 +467,10 @@ export interface TreeBranch extends IDisposable {
  * Doing that would however complicate trivial "hello world" style example slightly, as well as be a breaking API change.
  * It also seems more complex to handle invalidation with that pattern.
  * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.
+ *
+ * @see {@link TreeViewAlpha}
+ * @see {@link asTreeViewAlpha}
+ *
  * @sealed @public
  */
 export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {

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

@@ -174,7 +174,7 @@ export const treeNodeApi: TreeNodeApi = {
 								changedFields,
 								(field) =>
 									nodeSchema.storedKeyToPropertyKey.get(field) ??
-									fail(`Could not find stored key '${field}' in schema.`),
+									fail("Could not find stored key in schema."),
 							),
 						);
 						listener({ changedProperties });

package/src/simple-tree/arrayNode.ts

@@ -993,7 +993,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		if (!destinationField.context.isHydrated()) {
 			if (!(sourceField instanceof UnhydratedTreeSequenceField)) {
 				throw new UsageError(
-					"Cannot move elements from an unhydrated array to a hydrated array.",
+					"Cannot move elements from a hydrated array to an unhydrated array.",
 				);
 			}
 

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

@@ -6,7 +6,11 @@
 import type { TreeValue } from "../../core/index.js";
 import type { FlexTreeNode } from "../../feature-libraries/index.js";
 import { fail } from "../../util/index.js";
-import { type InnerNode, mapTreeNodeToProxy, proxySlot } from "./treeNodeKernel.js";
+import {
+	type InnerNode,
+	unhydratedFlexTreeNodeToTreeNode,
+	proxySlot,
+} from "./treeNodeKernel.js";
 import { getSimpleNodeSchemaFromInnerNode } from "./schemaCaching.js";
 import type { TreeNode, InternalTreeNode } from "./types.js";
 import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
@@ -20,7 +24,7 @@ import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
 export function getOrCreateNodeFromInnerNode(flexNode: InnerNode): TreeNode | TreeValue {
 	const cached =
 		flexNode instanceof UnhydratedFlexTreeNode
-			? mapTreeNodeToProxy.get(flexNode)
+			? unhydratedFlexTreeNodeToTreeNode.get(flexNode)
 			: flexNode.anchorNode.slots.get(proxySlot);
 
 	if (cached !== undefined) {

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

@@ -10,7 +10,7 @@ export {
 	tryGetTreeNodeSchema,
 	type InnerNode,
 	tryDisposeTreeNode,
-	tryGetTreeNodeFromMapNode,
+	unhydratedFlexTreeNodeToTreeNode,
 	getOrCreateInnerNode,
 	treeNodeFromAnchor,
 } from "./treeNodeKernel.js";

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

@@ -146,7 +146,7 @@ export class TreeNodeKernel {
 
 		if (innerNode instanceof UnhydratedFlexTreeNode) {
 			// Unhydrated case
-			mapTreeNodeToProxy.set(innerNode, node);
+			unhydratedFlexTreeNodeToTreeNodeInternal.set(innerNode, node);
 			// Register for change events from the unhydrated flex node.
 			// These will be fired if the unhydrated node is edited, and will also be forwarded later to the hydrated node.
 			this.#hydrationState = {
@@ -158,7 +158,7 @@ export class TreeNodeKernel {
 
 					let n: UnhydratedFlexTreeNode | undefined = innerNode;
 					while (n !== undefined) {
-						const treeNode = mapTreeNodeToProxy.get(n);
+						const treeNode = unhydratedFlexTreeNodeToTreeNodeInternal.get(n);
 						if (treeNode !== undefined) {
 							const kernel = getKernel(treeNode);
 							kernel.#unhydratedEvents.value.emit("subtreeChangedAfterBatch");
@@ -200,7 +200,7 @@ export class TreeNodeKernel {
 	private hydrate(anchorNode: AnchorNode): void {
 		assert(!this.disposed, 0xa2a /* cannot hydrate a disposed node */);
 		assert(!isHydrated(this.#hydrationState), 0xa2b /* hydration should only happen once */);
-		mapTreeNodeToProxy.delete(this.#hydrationState.innerNode);
+		unhydratedFlexTreeNodeToTreeNodeInternal.delete(this.#hydrationState.innerNode);
 		this.#hydrationState = this.createHydratedState(anchorNode);
 
 		// If needed, register forwarding emitters for events from before hydration
@@ -389,9 +389,20 @@ type KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;
 export type InnerNode = FlexTreeNode | UnhydratedFlexTreeNode;
 
 /**
- * {@inheritdoc proxyToMapTreeNode}
+ * Associates a given {@link UnhydratedFlexTreeNode} with a {@link TreeNode}.
  */
-export const mapTreeNodeToProxy = new WeakMap<UnhydratedFlexTreeNode, TreeNode>();
+const unhydratedFlexTreeNodeToTreeNodeInternal = new WeakMap<
+	UnhydratedFlexTreeNode,
+	TreeNode
+>();
+/**
+ * Retrieves the {@link TreeNode} associated with the given {@link UnhydratedFlexTreeNode} if any.
+ */
+export const unhydratedFlexTreeNodeToTreeNode =
+	unhydratedFlexTreeNodeToTreeNodeInternal as Pick<
+		WeakMap<UnhydratedFlexTreeNode, TreeNode>,
+		"get"
+	>;
 
 /**
  * An anchor slot which associates an anchor with its corresponding TreeNode, if there is one.
@@ -401,15 +412,6 @@ export const mapTreeNodeToProxy = new WeakMap<UnhydratedFlexTreeNode, TreeNode>(
  */
 export const proxySlot = anchorSlot<TreeNode>();
 
-/**
- * Retrieves the node associated with the given MapTreeNode node if any.
- */
-export function tryGetTreeNodeFromMapNode(
-	flexNode: UnhydratedFlexTreeNode,
-): TreeNode | undefined {
-	return mapTreeNodeToProxy.get(flexNode);
-}
-
 export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
 	const treeNode = anchorNode.slots.get(proxySlot);
 	if (treeNode !== undefined) {