@fluidframework/tree 2.40.0-336023 → 2.40.0

package/src/shared-tree/sharedTree.ts

@@ -13,6 +13,7 @@ import type { IChannelStorageService } from "@fluidframework/datastore-definitio
 import type {
 	IChannelView,
 	IFluidSerializer,
+	SharedKernel,
 } from "@fluidframework/shared-object-base/internal";
 import {
 	UsageError,
@@ -46,6 +47,7 @@ import {
 	DetachedFieldIndexSummarizer,
 	FieldKinds,
 	ForestSummarizer,
+	SchemaCodecVersion,
 	SchemaSummarizer,
 	TreeCompressionStrategy,
 	buildChunkedForest,
@@ -54,6 +56,7 @@ import {
 	jsonableTreeFromFieldCursor,
 	makeFieldBatchCodec,
 	makeMitigatedChangeFamily,
+	makeSchemaCodec,
 	makeTreeChunker,
 } from "../feature-libraries/index.js";
 import {
@@ -90,7 +93,14 @@ import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { type TreeCheckout, type BranchableTree, createTreeCheckout } from "./treeCheckout.js";
-import { type Breakable, breakingClass, throwIfBroken } from "../util/index.js";
+import {
+	type Breakable,
+	breakingClass,
+	type JsonCompatible,
+	throwIfBroken,
+} from "../util/index.js";
+// eslint-disable-next-line import/no-internal-modules
+import type { Format } from "../feature-libraries/schema-index/index.js";
 
 /**
  * Copy of data from an {@link ITreePrivate} at some point in time.
@@ -156,7 +166,7 @@ export interface ITreePrivate extends ITreeInternal {
  */
 interface ExplicitCodecVersions extends ExplicitCoreCodecVersions {
 	forest: number;
-	schema: number;
+	schema: SchemaCodecVersion;
 	detachedFieldIndex: number;
 	fieldBatch: number;
 }
@@ -186,18 +196,35 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 	return versions;
 }
 
+/**
+ * The type SharedTree's kernel's view must implement so what when its merged with the underling SharedObject's API it fully implements the required tree API surface ({@link ITreePrivate }).
+ */
+export type SharedTreeKernelView = Omit<ITreePrivate, keyof (IChannelView & IFluidLoadable)>;
+
 /**
  * SharedTreeCore, configured with a good set of indexes and field kinds which will maintain compatibility over time.
  *
  * TODO: detail compatibility requirements.
  */
 @breakingClass
-export class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange> {
+export class SharedTreeKernel
+	extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>
+	implements SharedKernel
+{
 	public readonly checkout: TreeCheckout;
 	public get storedSchema(): TreeStoredSchemaRepository {
 		return this.checkout.storedSchema;
 	}
 
+	/**
+	 * The app-facing API for SharedTree implemented by this Kernel.
+	 * @remarks
+	 * This is the API grafted onto the ISharedObject which apps can access.
+	 * It includes both the APIs used for internal testing, and public facing APIs (both stable and unstable).
+	 * Different users will have access to different subsets of this API, see {@link ITree}, {@link ITreeAlpha} and {@link ITreeInternal} which this {@link ITreePrivate} extends.
+	 */
+	public readonly view: SharedTreeKernelView;
+
 	public constructor(
 		breaker: Breakable,
 		sharedObject: IChannelView & IFluidLoadable,
@@ -219,9 +246,14 @@ export class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, Shar
 			idCompressor,
 			options,
 		);
-		const schemaSummarizer = new SchemaSummarizer(schema, options, {
-			getCurrentSeq: lastSequenceNumber,
-		});
+		const schemaCodec = makeSchemaCodec(options, codecVersions.schema);
+		const schemaSummarizer = new SchemaSummarizer(
+			schema,
+			{
+				getCurrentSeq: lastSequenceNumber,
+			},
+			schemaCodec,
+		);
 		const fieldBatchCodec = makeFieldBatchCodec(options, codecVersions.fieldBatch);
 
 		const encoderContext = {
@@ -331,6 +363,14 @@ export class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, Shar
 				}
 			}
 		});
+
+		this.view = {
+			contentSnapshot: () => this.contentSnapshot(),
+			exportSimpleSchema: () => this.exportSimpleSchema(),
+			exportVerbose: () => this.exportVerbose(),
+			viewWith: this.viewWith.bind(this),
+			kernel: this,
+		};
 	}
 
 	public exportVerbose(): VerboseTree | undefined {
@@ -450,6 +490,27 @@ export function exportSimpleSchema(storedSchema: TreeStoredSchema): SimpleTreeSc
 	};
 }
 
+/**
+ * A way to parse schema in the persisted format from {@link extractPersistedSchema}.
+ * @remarks
+ * This behaves identically to {@link ITreeAlpha.exportSimpleSchema},
+ * except that it gets the schema from the caller instead of from an existing tree.
+ *
+ * This can be useful for inspecting the contents of persisted schema,
+ * such as those generated by {@link extractPersistedSchema} for use in testing.
+ * Since that data format is otherwise unspecified,
+ * this provides a way to inspect its contents with documented semantics.
+ * @alpha
+ */
+export function persistedToSimpleSchema(
+	persisted: JsonCompatible,
+	options: ICodecOptions,
+): SimpleTreeSchema {
+	const schemaCodec = makeSchemaCodec(options, SchemaCodecVersion.v1);
+	const stored = schemaCodec.decode(persisted as Format);
+	return exportSimpleSchema(stored);
+}
+
 /**
  * Get a {@link BranchableTree} from a {@link ITree}.
  * @remarks The branch can be used for "version control"-style coordination of edits on the tree.

package/src/shared-tree/tree.ts

@@ -96,7 +96,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -117,7 +119,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -143,7 +147,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -165,7 +171,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -188,7 +196,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -205,7 +215,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -229,7 +241,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -254,7 +268,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -283,7 +299,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -309,7 +327,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -336,7 +356,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -360,7 +382,9 @@ export interface RunTransaction {
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.

package/src/shared-tree/treeAlpha.ts

@@ -34,8 +34,8 @@ import {
 	type VerboseTree,
 	toStoredSchema,
 	extractPersistedSchema,
-	TreeViewConfiguration,
 	type TreeBranch,
+	TreeViewConfigurationAlpha,
 } from "../simple-tree/index.js";
 import type { JsonCompatible } from "../util/index.js";
 import { noopValidator, type FluidClientVersion, type ICodecOptions } from "../codec/index.js";
@@ -52,6 +52,7 @@ import {
 } from "../feature-libraries/index.js";
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
+import { currentVersion } from "../codec/index.js";
 
 /**
  * Extensions to {@link (Tree:interface)} and {@link (TreeBeta:interface)} which are not yet stable.
@@ -197,7 +198,9 @@ export interface TreeAlpha {
 	 * This API could be improved:
 	 *
 	 * 1. It could validate that the schema is compatible, and return or throw an error in the invalid case (maybe add a "try" version).
+	 *
 	 * 2. A "try" version of this could return an error if the data isn't in a supported format (as determined by version and/or JasonValidator).
+	 *
 	 * 3. Requiring the caller provide a JsonValidator isn't the most friendly API. It might be practical to provide a default.
 	 */
 	importCompressed<const TSchema extends ImplicitFieldSchema>(
@@ -311,12 +314,12 @@ export const TreeAlpha: TreeAlpha = {
 			idCompressor?: IIdCompressor;
 		} & ICodecOptions,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+		const config = new TreeViewConfigurationAlpha({ schema });
 		const content: ViewContent = {
-			schema: extractPersistedSchema(schema),
+			schema: extractPersistedSchema(config, currentVersion),
 			tree: compressedData,
 			idCompressor: options.idCompressor ?? createIdCompressor(),
 		};
-		const config = new TreeViewConfiguration({ schema });
 		const view = independentInitializedView(config, options, content);
 		return TreeBeta.clone<TSchema>(view.root);
 	},

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

@@ -47,7 +47,6 @@ export class BranchCommitEnricher<TChange> {
 	/**
 	 * Process the given change, preparing new commits for {@link BranchCommitEnricher.enrich | enrichment}.
 	 * @param change - The change to process.
-	 * @param isAttached - Whether or not the SharedTree is attached to the service.
 	 */
 	public processChange(change: SharedTreeBranchChange<TChange>): void {
 		if (change.type === "append") {

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

@@ -40,12 +40,15 @@ export class TransactionEnricher<TChange> {
 
 	/**
 	 * Commits the current transaction.
-	 * @returns If and only if the closed transaction was the outermost transaction, returns a function which can be used to compute the composed change for that transaction's commits.
+	 * @returns A function which can be used to compute the composed change for that transaction's commits. Undefined if the transaction is still ongoing or contained no committed changes.
 	 */
 	public commitTransaction(): ((revision: RevisionTag) => TChange) | undefined {
 		const commitsCommitted = this.#transactionScopesStart.pop();
 		assert(commitsCommitted !== undefined, 0x985 /* No transaction to commit */);
 		if (this.#transactionScopesStart.length === 0) {
+			if (this.#transactionCommits.length === 0) {
+				return undefined;
+			}
 			const transactionCommits = this.#transactionCommits;
 			this.#transactionCommits = [];
 			return (revision: RevisionTag) =>

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

@@ -29,6 +29,7 @@ export {
 	type ScopedSchemaName,
 	type SchemaFactoryObjectOptions,
 	type SchemaStatics,
+	schemaStatics,
 } from "./schemaFactory.js";
 export { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 export type {
@@ -125,6 +126,7 @@ export {
 
 export { generateSchemaFromSimpleSchema } from "./schemaFromSimple.js";
 export { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
+export type { TreeChangeEvents } from "./treeChangeEvents.js";
 
 // Exporting the schema (RecursiveObject) to test that recursive types are working correctly.
 // These are `@internal` so they can't be included in the `InternalClassTreeTypes` due to https://github.com/microsoft/rushstack/issues/3639

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

@@ -182,7 +182,9 @@ export interface SchemaStatics {
 	 *
 	 * @remarks
 	 * The number is a {@link https://en.wikipedia.org/wiki/Double-precision_floating-point_format | double-precision 64-bit binary format IEEE 754} value, however there are some exceptions:
+	 *
 	 * - `NaN`, and the infinities are converted to `null` (and may therefore only be used where `null` is allowed by the schema).
+	 *
 	 * - `-0` may be converted to `0` in some cases.
 	 *
 	 * These limitations match the limitations of JSON.
@@ -429,9 +431,13 @@ const schemaStaticsPublic: SchemaStatics = schemaStatics;
  * It is legal to subclass the returned class, and even subclass that class,
  * but only a single class from that class hierarchy can ever be instantiated or passed to any API as a {@link TreeNodeSchema|schema}.
  * These base classes can be used with `instanceof`, but not with schema based APIs like `Tree.is`.
+ *
  * 2. If overriding the constructor, the constructor must accept the same argument as the base constructor `super` and forward it to `super` unchanged.
+ *
  * 3. Properties for fields defined in the schema should not be overridden.
+ *
  * 4. Additional static members added to schema should pick relatively unique keys to reduce the risk of colliding with implementation details what are not exposed in the API.
+ *
  * 5. If exporting the schema from a package which uses API-Extractor, export the base class and derived class separately to work around [a known limitation](https://github.com/microsoft/rushstack/issues/4429).
  *
  * Note:
@@ -1064,8 +1070,11 @@ export class SchemaFactory<
 	 * The identifier generated by the SharedTree has the following properties:
 	 *
 	 * - It is a UUID which will not collide with other generated UUIDs.
+	 *
 	 * - It is compressed to a space-efficient representation when stored in the document.
+	 *
 	 * - A compressed form of the identifier can be accessed at runtime via the {@link TreeNodeApi.shortId|Tree.shortId()} API.
+	 *
 	 * - It will error if read (and will not be present in the object's iterable properties) before the node has been inserted into a tree.
 	 *
 	 * However, a user may alternatively supply their own string as the identifier if desired (for example, if importing identifiers from another system).

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

@@ -3,29 +3,34 @@
  * Licensed under the MIT License.
  */
 
-import type { ICodecOptions } from "../../codec/index.js";
+import type { FluidClientVersion, ICodecOptions } from "../../codec/index.js";
 import type { TreeStoredSchema } from "../../core/index.js";
 import {
 	defaultSchemaPolicy,
 	encodeTreeSchema,
 	makeSchemaCodec,
+	SchemaCodecVersion,
 } from "../../feature-libraries/index.js";
-// eslint-disable-next-line import/no-internal-modules
-import type { Format } from "../../feature-libraries/schema-index/index.js";
+import {
+	clientVersionToSchemaVersion,
+	type Format,
+	// eslint-disable-next-line import/no-internal-modules
+} from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "../schemaTypes.js";
-import { toStoredSchema } from "../toStoredSchema.js";
+import { simpleToStoredSchema } from "../toStoredSchema.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";
 import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
+import type { SimpleTreeSchema } from "../simpleSchema.js";
 
 /**
- * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable, but unspecified format.
+ * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.
+ *
+ * @param schema - The schema to dump.
  *
  * @remarks
  * This can be used to help inspect schema for debugging, and to save a snapshot of schema to help detect and review changes to an applications schema.
- *
- * This format may change across major versions of this package: such changes are considered breaking.
- * Beyond that, no compatibility guarantee is provided for this format: it should never be relied upon to load data, it should only be used for comparing outputs from this function.
+ * This format is also compatible with {@link ViewContent.schema}, {@link comparePersistedSchema} and {@link persistedToSimpleSchema}.
  *
  * This only includes the "persisted" subset of schema information, which means the portion which gets included in documents.
  * It thus uses "persisted" keys, see {@link FieldProps.key}.
@@ -38,7 +43,7 @@ import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
  * An application could use this API to generate a `schema.json` file when it first releases,
  * then test that the schema is sill compatible with documents from that version with a test like :
  * ```typescript
- * assert.deepEqual(extractPersistedSchema(MySchema), require("./schema.json"));
+ * assert.deepEqual(extractPersistedSchema(MySchema, FluidClientVersion.v2_0), require("./schema.json"));
  * ```
  *
  * @privateRemarks
@@ -48,9 +53,13 @@ import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
  * Public API surface uses "persisted" terminology while internally we use "stored".
  * @alpha
  */
-export function extractPersistedSchema(schema: ImplicitFieldSchema): JsonCompatible {
-	const stored = toStoredSchema(schema);
-	return encodeTreeSchema(stored);
+export function extractPersistedSchema(
+	schema: SimpleTreeSchema,
+	oldestCompatibleClient: FluidClientVersion,
+): JsonCompatible {
+	const stored = simpleToStoredSchema(schema);
+	const writeVersion = clientVersionToSchemaVersion(oldestCompatibleClient);
+	return encodeTreeSchema(stored, writeVersion);
 }
 
 /**
@@ -89,7 +98,9 @@ export function comparePersistedSchema(
 	options: ICodecOptions,
 	canInitialize: boolean,
 ): SchemaCompatibilityStatus {
-	const schemaCodec = makeSchemaCodec(options);
+	// Any version can be passed down to makeSchemaCodec here.
+	// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.
+	const schemaCodec = makeSchemaCodec(options, SchemaCodecVersion.v1);
 	const stored = schemaCodec.decode(persisted as Format);
 	const viewSchema = new SchemaCompatibilityTester(
 		defaultSchemaPolicy,

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

@@ -290,14 +290,18 @@ export interface TreeViewAlpha<
 	 * "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
 	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
 	 * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:
+	 *
 	 * - A "success" flag indicating whether the transaction was successful or not.
+	 *
 	 * - The success of failure value as returned by the transaction function.
 	 * @remarks
 	 * This API will throw an error if the constraints are not met or something unexpected happens.
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -305,9 +309,12 @@ export interface TreeViewAlpha<
 	 *
 	 * Nested transactions:
 	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
+	 *
 	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
+	 *
 	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
 	 * for the outermost transaction which includes all inner transactions.
+	 *
 	 * - Undo will undo the outermost transaction and all inner transactions.
 	 */
 	runTransaction<TSuccessValue, TFailureValue>(
@@ -317,10 +324,13 @@ export interface TreeViewAlpha<
 	/**
 	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
 	 * @param transaction - The function to run as the body of the transaction. It may return the following:
+	 *
 	 * - Nothing to indicate that the body of the transaction has successfully run.
+	 *
 	 * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a "rollback" property which
 	 * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so
 	 * far. "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
+	 *
 	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
 	 * @returns A result object of {@link TransactionResult | TransactionResult} type. It includes a "success" flag indicating whether the
 	 * transaction was successful or not.
@@ -329,7 +339,9 @@ export interface TreeViewAlpha<
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -337,9 +349,12 @@ export interface TreeViewAlpha<
 	 *
 	 * Nested transactions:
 	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
+	 *
 	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
+	 *
 	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
 	 * for the outermost transaction which includes all inner transactions.
+	 *
 	 * - Undo will undo the outermost transaction and all inner transactions.
 	 */
 	runTransaction(
@@ -363,7 +378,9 @@ export interface SchemaCompatibilityStatus {
 	 * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.
 	 *
 	 * Examples which are expressible where this may occur include:
+	 *
 	 * - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)
+	 *
 	 * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (ex: an object node type containing a required field with no allowed types)
 	 *
 	 * These cases are typically not interesting to applications.
@@ -441,11 +458,15 @@ export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied">
 
 	/**
 	 * Fired when:
+	 *
 	 * - a local commit is applied outside of a transaction
+	 *
 	 * - a local transaction is committed
 	 *
 	 * The event is not fired when:
+	 *
 	 * - a local commit is applied within a transaction
+	 *
 	 * - a remote commit is applied
 	 *
 	 * @param data - information about the commit that was applied
@@ -481,11 +502,15 @@ export interface TreeViewEvents {
 
 	/**
 	 * Fired when:
+	 *
 	 * - a local commit is applied outside of a transaction
+	 *
 	 * - a local transaction is committed
 	 *
 	 * The event is not fired when:
+	 *
 	 * - a local commit is applied within a transaction
+	 *
 	 * - a remote commit is applied
 	 *
 	 * @param data - information about the commit that was applied

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

@@ -7,7 +7,6 @@ import {
 	getKernel,
 	isTreeNode,
 	type NodeKind,
-	type TreeChangeEvents,
 	type TreeNode,
 	type Unhydrated,
 	type WithType,
@@ -15,6 +14,7 @@ import {
 import { treeNodeApi } from "./treeNodeApi.js";
 import { createFromCursor } from "./create.js";
 import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../schemaTypes.js";
+import type { TreeChangeEvents } from "./treeChangeEvents.js";
 
 // Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,
 // and where most of the actual implementation is for much of it.
@@ -122,7 +122,9 @@ export interface TreeBeta {
 	 *
 	 * - Local state, such as properties added to customized schema classes, will not be cloned. However, they will be
 	 * initialized to their default state just as if the node had been created via its constructor.
+	 *
 	 * - Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.
+	 *
 	 * - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.
 	 */
 	clone<const TSchema extends ImplicitFieldSchema>(