@fluidframework/tree 2.90.0-378676 → 2.90.0

package/src/shared-tree-core/editManager.ts

@@ -23,7 +23,6 @@ import {
 	mintCommit,
 	type RebaseStatsWithDuration,
 	tagChange,
-	type EditorOptions,
 } from "../core/index.js";
 import { type Mutable, brand, getOrCreate, mapIterable } from "../util/index.js";
 
@@ -124,7 +123,6 @@ export class EditManager<
 		public readonly localSessionId: SessionId,
 		private readonly mintRevisionTag: () => RevisionTag,
 		private readonly onSharedBranchCreated?: (branchId: BranchId) => void,
-		editorOptions?: EditorOptions,
 		logger?: ITelemetryLoggerExt,
 	) {
 		this.trunkBase = {
@@ -149,10 +147,9 @@ export class EditManager<
 			mintRevisionTag,
 			this._events,
 			this.telemetryEventBatcher,
-			editorOptions,
 		);
 
-		this.createAndAddSharedBranch("main", undefined, undefined, mainTrunk, editorOptions);
+		this.createAndAddSharedBranch("main", undefined, undefined, mainTrunk);
 	}
 
 	public getLocalBranch(branchId: BranchId): SharedTreeBranch<TEditor, TChangeset> {
@@ -483,15 +480,8 @@ export class EditManager<
 		sessionId: SessionId | undefined,
 		parent: SharedBranch<TEditor, TChangeset> | undefined,
 		branch: SharedTreeBranch<TEditor, TChangeset>,
-		editorOptions?: EditorOptions,
 	): SharedBranch<TEditor, TChangeset> {
-		const sharedBranch = this.createSharedBranch(
-			branchId,
-			sessionId,
-			parent,
-			branch,
-			editorOptions,
-		);
+		const sharedBranch = this.createSharedBranch(branchId, sessionId, parent, branch);
 		this.addSharedBranch(branchId, sharedBranch);
 		return sharedBranch;
 	}
@@ -522,7 +512,6 @@ export class EditManager<
 		sessionId: SessionId | undefined,
 		parent: SharedBranch<TEditor, TChangeset> | undefined,
 		branch: SharedTreeBranch<TEditor, TChangeset>,
-		editorOptions?: EditorOptions,
 	): SharedBranch<TEditor, TChangeset> {
 		const sharedBranch = new SharedBranch(
 			parent,
@@ -534,7 +523,6 @@ export class EditManager<
 			this.mintRevisionTag,
 			this._events,
 			this.telemetryEventBatcher,
-			editorOptions,
 		);
 
 		return sharedBranch;
@@ -707,7 +695,6 @@ class SharedBranch<TEditor extends ChangeFamilyEditor, TChangeset> {
 		private readonly mintRevisionTag: () => RevisionTag,
 		branchTrimmer: Listenable<BranchTrimmingEvents>,
 		telemetryEventBatcher: TelemetryEventBatcher<keyof RebaseStatsWithDuration> | undefined,
-		editorOptions?: EditorOptions,
 	) {
 		this.localBranch = new SharedTreeBranch(
 			this.trunk.getHead(),
@@ -715,7 +702,6 @@ class SharedBranch<TEditor extends ChangeFamilyEditor, TChangeset> {
 			mintRevisionTag,
 			branchTrimmer,
 			telemetryEventBatcher,
-			editorOptions,
 		);
 
 		this.sequenceIdToCommit.set(baseCommitSequenceId, this.trunk.getHead());

package/src/shared-tree-core/editManagerCodecs.ts

@@ -74,15 +74,6 @@ export function editManagerFormatVersionSelectorForSharedBranches(
 	return brand(EditManagerFormatVersion.vSharedBranches);
 }
 
-/**
- * Returns the version that should be used for testing shared branches.
- */
-export function editManagerFormatVersionSelectorForDetachedRootEditing(
-	clientVersion: MinimumVersionForCollab,
-): EditManagerFormatVersion {
-	return brand(EditManagerFormatVersion.vDetachedRoots);
-}
-
 export interface EditManagerCodecOptions {
 	readonly editManagerFormatSelector?: (
 		minVersionForCollab: MinimumVersionForCollab,
@@ -150,8 +141,7 @@ export function makeEditManagerCodecs<TChangeset>(
 			}
 			case unbrand(EditManagerFormatVersion.v3):
 			case unbrand(EditManagerFormatVersion.v4):
-			case unbrand(EditManagerFormatVersion.v6):
-			case unbrand(EditManagerFormatVersion.vDetachedRoots): {
+			case unbrand(EditManagerFormatVersion.v6): {
 				const changeCodec = changeCodecs.resolve(dependentChangeFormatVersion.lookup(version));
 				return [
 					version,

package/src/shared-tree-core/editManagerFormatCommons.ts

@@ -167,11 +167,6 @@ export const EditManagerFormatVersion = strictEnum("editManager.FormatVersion",
 	 * Only used for testing shared branches.
 	 */
 	vSharedBranches: "shared-branches|v0.1",
-	/**
-	 * Not yet released.
-	 * Only used for testing detached roots.
-	 */
-	vDetachedRoots: "detached-roots|v0.1",
 });
 export type EditManagerFormatVersion = Values<typeof EditManagerFormatVersion>;
 export const supportedEditManagerFormatVersions: ReadonlySet<EditManagerFormatVersion> =
@@ -180,7 +175,6 @@ export const supportedEditManagerFormatVersions: ReadonlySet<EditManagerFormatVe
 		EditManagerFormatVersion.v4,
 		EditManagerFormatVersion.v6,
 		EditManagerFormatVersion.vSharedBranches,
-		EditManagerFormatVersion.vDetachedRoots,
 	]);
 export const editManagerFormatVersions: ReadonlySet<EditManagerFormatVersion> = new Set(
 	Object.values(EditManagerFormatVersion),

package/src/shared-tree-core/editManagerFormatV1toV4.ts

@@ -28,8 +28,7 @@ export interface EncodedEditManager<TChangeset> {
 		| typeof EditManagerFormatVersion.v2
 		| typeof EditManagerFormatVersion.v3
 		| typeof EditManagerFormatVersion.v4
-		| typeof EditManagerFormatVersion.v6
-		| typeof EditManagerFormatVersion.vDetachedRoots;
+		| typeof EditManagerFormatVersion.v6;
 }
 
 export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
@@ -41,7 +40,6 @@ export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: Change
 				Type.Literal(EditManagerFormatVersion.v3),
 				Type.Literal(EditManagerFormatVersion.v4),
 				Type.Literal(EditManagerFormatVersion.v6),
-				Type.Literal(EditManagerFormatVersion.vDetachedRoots),
 			]),
 			trunk: Type.Array(SequencedCommit(tChange)),
 			branches: Type.Array(Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange)])),

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

@@ -48,7 +48,6 @@ export {
 	type EditManagerCodecOptions,
 	clientVersionToEditManagerFormatVersion,
 	editManagerFormatVersionSelectorForSharedBranches,
-	editManagerFormatVersionSelectorForDetachedRootEditing,
 } from "./editManagerCodecs.js";
 export {
 	EditManagerFormatVersion,
@@ -74,7 +73,6 @@ export {
 	getCodecTreeForMessageFormatWithChange,
 	clientVersionToMessageFormatVersion,
 	messageFormatVersionSelectorForSharedBranches,
-	messageFormatVersionSelectorForDetachedRootEditing,
 	makeMessageCodec,
 	type MessageEncodingContext,
 } from "./messageCodecs.js";

package/src/shared-tree-core/messageCodecV1ToV4.ts

@@ -35,8 +35,7 @@ export function makeV1ToV4CodecWithVersion<TChangeset>(
 		| typeof MessageFormatVersion.v2
 		| typeof MessageFormatVersion.v3
 		| typeof MessageFormatVersion.v4
-		| typeof MessageFormatVersion.v6
-		| typeof MessageFormatVersion.vDetachedRoots,
+		| typeof MessageFormatVersion.v6,
 ): IJsonCodec<
 	DecodedMessage<TChangeset>,
 	JsonCompatibleReadOnly,

package/src/shared-tree-core/messageCodecs.ts

@@ -83,15 +83,6 @@ export function messageFormatVersionSelectorForSharedBranches(
 	return brand(MessageFormatVersion.vSharedBranches);
 }
 
-/**
- * Returns the version that should be used for testing detached root editing.
- */
-export function messageFormatVersionSelectorForDetachedRootEditing(
-	clientVersion: MinimumVersionForCollab,
-): MessageFormatVersion {
-	return brand(MessageFormatVersion.vDetachedRoots);
-}
-
 export function makeMessageCodec<TChangeset>(
 	changeCodecs: ICodecFamily<TChangeset, ChangeEncodingContext>,
 	dependentChangeFormatVersion: DependentFormatVersion<MessageFormatVersion>,
@@ -154,8 +145,7 @@ export function makeMessageCodecs<TChangeset>(
 			}
 			case unbrand(MessageFormatVersion.v3):
 			case unbrand(MessageFormatVersion.v4):
-			case unbrand(MessageFormatVersion.v6):
-			case unbrand(MessageFormatVersion.vDetachedRoots): {
+			case unbrand(MessageFormatVersion.v6): {
 				const changeCodec = changeCodecs.resolve(dependentChangeFormatVersion.lookup(version));
 				return [
 					version,

package/src/shared-tree-core/messageFormat.ts

@@ -57,11 +57,6 @@ export const MessageFormatVersion = strictEnum("MessageFormatVersion", {
 	 * Only used for testing shared branches.
 	 */
 	vSharedBranches: "shared-branches|v0.1",
-	/**
-	 * Not yet released.
-	 * Only used for testing detached roots.
-	 */
-	vDetachedRoots: "detached-roots|v0.1",
 });
 export type MessageFormatVersion = Values<typeof MessageFormatVersion>;
 export const supportedMessageFormatVersions: ReadonlySet<MessageFormatVersion> = new Set([
@@ -69,7 +64,6 @@ export const supportedMessageFormatVersions: ReadonlySet<MessageFormatVersion> =
 	MessageFormatVersion.v4,
 	MessageFormatVersion.v6,
 	MessageFormatVersion.vSharedBranches,
-	MessageFormatVersion.vDetachedRoots,
 ]);
 export const messageFormatVersions: ReadonlySet<MessageFormatVersion> = new Set(
 	Object.values(MessageFormatVersion),

package/src/shared-tree-core/messageFormatV1ToV4.ts

@@ -39,8 +39,7 @@ export interface Message {
 		| typeof MessageFormatVersion.v2
 		| typeof MessageFormatVersion.v3
 		| typeof MessageFormatVersion.v4
-		| typeof MessageFormatVersion.v6
-		| typeof MessageFormatVersion.vDetachedRoots;
+		| typeof MessageFormatVersion.v6;
 }
 
 // Return type is intentionally derived.
@@ -57,7 +56,6 @@ export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 				Type.Literal(MessageFormatVersion.v3),
 				Type.Literal(MessageFormatVersion.v4),
 				Type.Literal(MessageFormatVersion.v6),
-				Type.Literal(MessageFormatVersion.vDetachedRoots),
 			]),
 		),
 	});

package/src/shared-tree-core/sharedTreeCore.ts

@@ -80,9 +80,7 @@ export interface ClonableSchemaAndPolicy extends SchemaAndPolicy {
 export interface SharedTreeCoreOptionsInternal
 	extends CodecWriteOptions,
 		EditManagerCodecOptions,
-		MessageCodecOptions {
-	readonly enableDetachedRootEditing: boolean;
-}
+		MessageCodecOptions {}
 
 export interface EnrichmentConfig<TChange> {
 	readonly enricher: ChangeEnricher<TChange>;
@@ -182,7 +180,6 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			localSessionId,
 			this.mintRevisionTag,
 			(branchId) => this.registerSharedBranch(branchId),
-			options,
 			rebaseLogger,
 		);
 

package/src/shared-tree-core/transaction.ts

@@ -44,27 +44,14 @@ export enum TransactionResult {
 export interface Transactor {
 	/**
 	 * Start a new transaction.
+	 * @remarks
 	 * If a transaction is already in progress when this new transaction starts, then this transaction will be "nested" inside of it,
 	 * i.e. the outer transaction will still be in progress after this new transaction is committed or aborted.
-	 * @param isAsync - Whether the transaction is asynchronous.
-	 * An error will be thrown if an asynchronous transaction is started while a synchronous transaction is in progress.
-	 *
-	 * @remarks Asynchronous transactions are not supported on the root checkout,
-	 * since it is always kept up-to-date with the latest remote edits and the results of this rebasing (which might invalidate
-	 * the transaction) is not visible to the application author.
-	 * Instead,
-	 *
-	 * 1. fork the root checkout
-	 * 2. run the transaction on the fork
-	 * 3. merge the fork back into the root checkout
-	 *
-	 * @privateRemarks There is currently no enforcement that asynchronous transactions don't happen on the root checkout.
-	 * AB#6488 tracks adding some enforcement to make it more clear to application authors that this is not supported.
 	 */
-	start(isAsync: boolean): void;
+	start(): void;
 	/**
 	 * Close this transaction by squashing its edits and committing them as a single edit.
-	 * If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.
+	 * @remarks If this is the root checkout and there are no ongoing transactions remaining, the squashed edit will be submitted to Fluid.
 	 */
 	commit(): void;
 	/**
@@ -72,9 +59,10 @@ export interface Transactor {
 	 */
 	abort(): void;
 	/**
-	 * True if there is at least one transaction currently in progress on this view, otherwise false.
+	 * The number of transactions currently in progress, including any nested transactions.
+	 * @remarks This is 0 when no transaction is in progress, 1 when a single transaction is in progress, 2 when a transaction is nested inside another, etc.
 	 */
-	isInProgress(): boolean;
+	size: number;
 	/**
 	 * Provides events for changes in transaction progress.
 	 */
@@ -84,17 +72,17 @@ export interface Transactor {
 export interface TransactionEvents {
 	/**
 	 * Raised just after a transaction has begun.
-	 * @remarks When this event fires, {@link Transactor.isInProgress} will be true because the transaction has already begun.
+	 * @remarks When this event fires, {@link Transactor.size} will be greater than 0 because the transaction has already begun.
 	 */
 	started(): void;
 	/**
 	 * Raised just before a transaction is aborted.
-	 * @remarks When this event fires, {@link Transactor.isInProgress} will still be true because the transaction has not yet ended.
+	 * @remarks When this event fires, {@link Transactor.size} will still be greater than 0 because the transaction has not yet ended.
 	 */
 	aborting(): void;
 	/**
 	 * Raised just before a transaction is committed.
-	 * @remarks When this event fires, {@link Transactor.isInProgress} will still be true because the transaction has not yet ended.
+	 * @remarks When this event fires, {@link Transactor.size} will still be greater than 0 because the transaction has not yet ended.
 	 */
 	committing(): void;
 }
@@ -122,13 +110,13 @@ export interface Callbacks {
 /**
  * A function that will be called when a transaction is pushed to the {@link TransactionStack | stack}.
  * @remarks This function may return other functions that will be called when the transaction is popped from the stack or a nested transaction is pushed onto the stack.
- * This function runs just before the transaction begins, so if this is the beginning of an outermost (not nested) transaction then {@link Transactor.isInProgress} will be false during its execution.
+ * This function runs just before the transaction begins, so if this is the beginning of an outermost (not nested) transaction then {@link Transactor.size} will be 0 during its execution.
  */
 export type OnPush = () => Callbacks | void;
 
 /**
  * A function that will be called when a transaction is popped from the {@link TransactionStack | stack}.
- * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.isInProgress} will be false during its execution.
+ * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.size} will be 0 during its execution.
  */
 export type OnPop = (result: TransactionResult) => void;
 
@@ -138,8 +126,6 @@ export type OnPop = (result: TransactionResult) => void;
 interface TransactionStackFrame {
 	/** The callbacks provided when this transaction frame was pushed onto the stack. */
 	readonly callbacks: Callbacks;
-	/** Whether this transaction frame is asynchronous. */
-	readonly isAsync: boolean;
 }
 
 /**
@@ -168,31 +154,25 @@ export class TransactionStack implements Transactor, IDisposable {
 		this.#onPush = onPush;
 	}
 
-	public isInProgress(): boolean {
+	public get size(): number {
 		this.ensureNotDisposed();
-		return this.#stack.length > 0;
+		return this.#stack.length;
 	}
 
-	public start(isAsync: boolean): void {
+	public start(): void {
 		this.ensureNotDisposed();
 		const last = getLast(this.#stack);
-		if (last !== undefined && !last.isAsync && isAsync) {
-			throw new UsageError(
-				"An asynchronous transaction cannot be started while a synchronous transaction is in progress.",
-			);
-		}
 		const onPushCurrent = last === undefined ? this.#onPush : last.callbacks.onPush;
 		const { onPush, onPop } = onPushCurrent?.() ?? {};
 		this.#stack.push({
 			callbacks: { onPop, onPush: onPush ?? onPushCurrent },
-			isAsync,
 		});
 		this.#events.emit("started");
 	}
 
 	public commit(): void {
 		this.ensureNotDisposed();
-		if (!this.isInProgress()) {
+		if (this.size === 0) {
 			throw new UsageError("No transaction to commit");
 		}
 		this.#events.emit("committing");
@@ -201,7 +181,7 @@ export class TransactionStack implements Transactor, IDisposable {
 
 	public abort(): void {
 		this.ensureNotDisposed();
-		if (!this.isInProgress()) {
+		if (this.size === 0) {
 			throw new UsageError("No transaction to abort");
 		}
 		this.#events.emit("aborting");
@@ -210,7 +190,7 @@ export class TransactionStack implements Transactor, IDisposable {
 
 	public dispose(): void {
 		this.ensureNotDisposed();
-		while (this.isInProgress()) {
+		while (this.size > 0) {
 			this.abort();
 		}
 		this.#disposed = true;
@@ -225,7 +205,7 @@ export class TransactionStack implements Transactor, IDisposable {
 
 /**
  * A function that will be called when a transaction is popped from the {@link SquashingTransactionStack | stack}.
- * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.isInProgress} will be false during its execution.
+ * @remarks This function runs just after the transaction ends, so if this is the end of an outermost (not nested) transaction then {@link Transactor.size} will be 0 during its execution.
  * @param result - The result of the transaction.
  * @param viewUpdate - The change that needs to be applied to the view to keep it up-to-date with the branch after the transaction ends.
  * This is needed in asynchronous transactions where new commits have been added to the branch while the transaction was in progress.
@@ -328,7 +308,7 @@ export class SquashingTransactionStack<
 
 				// Invoked when an outer transaction ends
 				const onOuterTransactionPop: OnPop = (result) => {
-					assert(!this.isInProgress(), 0xcae /* The outer transaction should be ending */);
+					assert(this.size === 0, 0xcae /* The outer transaction should be ending */);
 					transactionBranch.editor.exitTransaction();
 
 					const sourcePath: GraphCommit<TChange>[] = [];

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

@@ -147,6 +147,10 @@ export interface ITreeViewConfiguration<
 > extends ITreeConfigurationOptions {
 	/**
 	 * The schema which the application wants to view the tree with.
+	 * @remarks
+	 * Use {@link SchemaFactory} to construct the schema.
+	 * Changes to this schema between different versions have important compatibility implications.
+	 * See the {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution | documentation on schema evolution} for more details.
 	 */
 	readonly schema: TSchema;
 }

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

@@ -5,13 +5,13 @@
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { TreeIndexKey } from "../../feature-libraries/index.js";
+import type { TreeIndex } from "../../feature-libraries/index.js";
 import type { TreeNode } from "../core/index.js";
 import { FieldKind, type ImplicitFieldSchema } from "../fieldSchema.js";
 import { ObjectNodeSchema } from "../node-kinds/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
 
-import { createSimpleTreeIndex, type SimpleTreeIndex } from "./simpleTreeIndex.js";
+import { createTreeIndex, type TreeIndexKey } from "./simpleTreeIndex.js";
 import type { TreeView } from "./tree.js";
 
 /**
@@ -19,7 +19,7 @@ import type { TreeView } from "./tree.js";
  *
  * @alpha
  */
-export type IdentifierIndex = SimpleTreeIndex<string, TreeNode>;
+export type IdentifierIndex = TreeIndex<string, TreeNode>;
 
 function isStringKey(key: TreeIndexKey): key is string {
 	return typeof key === "string";
@@ -49,7 +49,7 @@ export function createIdentifierIndex<TSchema extends ImplicitFieldSchema>(
 		},
 	});
 
-	return createSimpleTreeIndex(
+	return createTreeIndex(
 		view,
 		(schemus) => identifierFields.get(schemus.identifier),
 		(nodes) => {

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

@@ -22,6 +22,7 @@ export type {
 	TreeBranch,
 	TreeBranchAlpha,
 	TreeBranchEvents,
+	TreeContextAlpha,
 	ITreeAlpha,
 } from "./tree.js";
 export { asTreeViewAlpha } from "./tree.js";
@@ -141,7 +142,7 @@ export {
 	TreeBeta,
 	type TreeChangeEventsBeta,
 } from "./treeBeta.js";
-export { createSimpleTreeIndex, type SimpleTreeIndex } from "./simpleTreeIndex.js";
+export { createTreeIndex, type TreeIndexKey } from "./simpleTreeIndex.js";
 export {
 	createIdentifierIndex,
 	type IdentifierIndex,
@@ -164,6 +165,7 @@ export {
 	type TransactionResultExt,
 	type TransactionResultSuccess,
 	type TransactionResultFailed,
+	type WithValue,
 	rollback,
 } from "./transactionTypes.js";
 

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

@@ -226,12 +226,13 @@ export const SchemaFactory_base = classWithStatics(schemaStaticsPublic);
  * @remarks
  * For details related to inputting data constrained by schema (including via assignment), and how non-exact schema types are handled in general refer to {@link Input}.
  * For information about recursive schema support, see methods postfixed with "recursive" and {@link ValidateRecursiveSchema}.
- * To apply schema defined with this factory to a tree, see {@link ViewableTree.viewWith} and {@link TreeViewConfiguration}.
+ * To apply schema defined with this factory to a tree, see {@link TreeViewConfiguration} and {@link ViewableTree.viewWith}.
+ * See the {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution | documentation on schema evolution} for how to handle changes to schema over time.
  *
  * All schema produced by this factory get a {@link TreeNodeSchemaCore.identifier|unique identifier} by combining the {@link SchemaFactory.scope} with the schema's `Name`.
  * The `Name` part may be explicitly provided as a parameter, or inferred as a structural combination of the provided types.
  * The APIs which use this second approach, structural naming, also deduplicate all equivalent calls.
- * Therefor two calls to `array(allowedTypes)` with the same allowedTypes will return the same {@link TreeNodeSchema} instance.
+ * Therefore two calls to `array(allowedTypes)` with the same allowedTypes will return the same {@link TreeNodeSchema} instance.
  * On the other hand, two calls to `array(name, allowedTypes)` will always return different {@link TreeNodeSchema} instances
  * and it is an error to use both in the same tree (since their identifiers are not unique).
  *

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

@@ -17,7 +17,6 @@ import {
 	type TreeIndexNodes,
 	hasElement,
 	type TreeIndex,
-	type TreeIndexKey,
 	type KeyFinder,
 } from "../../feature-libraries/index.js";
 import type { SchematizingSimpleTreeView } from "../../shared-tree/index.js";
@@ -27,6 +26,7 @@ import {
 	type TreeNode,
 	type TreeNodeSchema,
 	type NodeFromSchema,
+	type TreeLeafValue,
 } from "../core/index.js";
 import type { ImplicitFieldSchema } from "../fieldSchema.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
@@ -35,14 +35,16 @@ import type { TreeView } from "./tree.js";
 import { treeNodeApi } from "./treeNodeApi.js";
 
 /**
- * A {@link TreeIndex} that returns tree nodes given their associated keys.
- *
+ * Value that may be used as keys in a {@link TreeIndex}.
+ * @remarks
+ * This supports values which have value semantics and are compared by value, just like {@link TreeLeafValue}.
+ * This allows using any tree value as a key (for example in an index tracking where those values occur in the tree).
  * @alpha
  */
-export type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey, TValue>;
+export type TreeIndexKey = TreeLeafValue;
 
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema
@@ -52,7 +54,7 @@ export type SimpleTreeIndex<TKey extends TreeIndexKey, TValue> = TreeIndex<TKey,
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -61,9 +63,10 @@ export function createSimpleTreeIndex<
 	indexer: (schema: TreeNodeSchema) => string | undefined,
 	getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema
@@ -74,7 +77,7 @@ export function createSimpleTreeIndex<
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -85,9 +88,10 @@ export function createSimpleTreeIndex<
 	getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
 	indexableSchema: readonly TSchema[],
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema
@@ -97,7 +101,7 @@ export function createSimpleTreeIndex<
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -106,9 +110,10 @@ export function createSimpleTreeIndex<
 	indexer: Map<TreeNodeSchema, string>,
 	getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @param view - the view for the tree being indexed
  * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema
@@ -119,7 +124,7 @@ export function createSimpleTreeIndex<
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -130,13 +135,14 @@ export function createSimpleTreeIndex<
 	getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
 	indexableSchema: readonly TSchema[],
-): SimpleTreeIndex<TKey, TValue>;
+): TreeIndex<TKey, TValue>;
+
 /**
- * Creates a {@link SimpleTreeIndex} with a specified indexer.
+ * Creates a {@link TreeIndex} with a specified indexer.
  *
  * @alpha
  */
-export function createSimpleTreeIndex<
+export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
 	TKey extends TreeIndexKey,
 	TValue,
@@ -148,7 +154,7 @@ export function createSimpleTreeIndex<
 		| ((nodes: TreeIndexNodes<NodeFromSchema<TreeNodeSchema>>) => TValue),
 	isKeyValid: (key: TreeIndexKey) => key is TKey,
 	indexableSchema?: readonly TreeNodeSchema[],
-): SimpleTreeIndex<TKey, TValue> {
+): TreeIndex<TKey, TValue> {
 	const indexableSchemaMap = new Map<string, TreeNodeSchema>();
 	if (indexableSchema === undefined) {
 		walkFieldSchema(view.schema, {
@@ -214,7 +220,7 @@ export function createSimpleTreeIndex<
 
 	// all the type checking guarantees that we put nodes of the correct type in the index
 	// but it's not captured in the type system
-	return index as SimpleTreeIndex<TKey, TValue>;
+	return index as TreeIndex<TKey, TValue>;
 }
 
 function makeGenericKeyFinder<TKey extends TreeIndexKey>(