@fluidframework/tree 2.91.0 → 2.93.0

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

@@ -51,14 +51,10 @@ import { BranchCommitEnricher } from "./branchCommitEnricher.js";
 import type { ChangeEnricher } from "./changeEnricher.js";
 import { DefaultResubmitMachine } from "./defaultResubmitMachine.js";
 import { EditManager, minimumPossibleSequenceNumber } from "./editManager.js";
-import { makeEditManagerCodec, type EditManagerCodecOptions } from "./editManagerCodecs.js";
+import { makeEditManagerCodecBuilder } from "./editManagerCodecs.js";
 import type { EditManagerFormatVersion, SeqNumber } from "./editManagerFormatCommons.js";
 import { EditManagerSummarizer } from "./editManagerSummarizer.js";
-import {
-	type MessageCodecOptions,
-	type MessageEncodingContext,
-	makeMessageCodec,
-} from "./messageCodecs.js";
+import { type MessageEncodingContext, makeMessageCodecBuilder } from "./messageCodecs.js";
 import type { MessageFormatVersion } from "./messageFormat.js";
 import type { DecodedMessage } from "./messageTypes.js";
 import type { ResubmitMachine } from "./resubmitMachine.js";
@@ -77,10 +73,7 @@ export interface ClonableSchemaAndPolicy extends SchemaAndPolicy {
 	schema: TreeStoredSchemaRepository;
 }
 
-export interface SharedTreeCoreOptionsInternal
-	extends CodecWriteOptions,
-		EditManagerCodecOptions,
-		MessageCodecOptions {}
+export interface SharedTreeCoreOptionsInternal extends CodecWriteOptions {}
 
 export interface EnrichmentConfig<TChange> {
 	readonly enricher: ChangeEnricher<TChange>;
@@ -186,12 +179,12 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		this.registerSharedBranch("main");
 
 		const revisionTagCodec = new RevisionTagCodec(idCompressor);
-		const editManagerCodec = makeEditManagerCodec(
-			this.editManager.changeFamily.codecs,
-			changeFormatVersionForEditManager,
+		const editManagerCodec = makeEditManagerCodecBuilder<TChange>().build({
+			...options,
+			changeCodecs: this.editManager.changeFamily.codecs,
+			dependentChangeFormatVersion: changeFormatVersionForEditManager,
 			revisionTagCodec,
-			options,
-		);
+		});
 		this.summarizables = [
 			new EditManagerSummarizer(
 				this.editManager,
@@ -207,12 +200,12 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			0x350 /* Index summary element keys must be unique */,
 		);
 
-		this.messageCodec = makeMessageCodec(
-			changeFamily.codecs,
-			changeFormatVersionForMessage,
-			new RevisionTagCodec(idCompressor),
-			options,
-		);
+		this.messageCodec = makeMessageCodecBuilder<TChange>().build({
+			...options,
+			changeCodecs: changeFamily.codecs,
+			dependentChangeFormatVersion: changeFormatVersionForMessage,
+			revisionTagCodec: new RevisionTagCodec(idCompressor),
+		});
 
 		if (enrichmentConfig !== undefined) {
 			this.registerSharedBranchForEditing(

package/src/sharedTreeAttributes.ts

@@ -12,6 +12,9 @@ import { pkgVersion } from "./packageVersion.js";
  * @beta
  * @legacy
  */
+// New type string, to be activated once the migration has been fully shipped dark and is safe to flip.
+// See LegacyTypeAwareRegistry in packages/runtime/datastore/src/dataStoreRuntime.ts.
+// export const SharedTreeFactoryType = "tree";
 export const SharedTreeFactoryType = "https://graph.microsoft.com/types/tree";
 
 /**

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

@@ -363,7 +363,12 @@ function* getFieldDiscrepancies(
 		fail(0xbef /* A conversion from a FieldKind to a FlexFieldKind should exist */);
 
 	// This checks if the field kind in the view schema is not compatible with the stored schema.
-	if (viewKind.identifier !== stored.kind) {
+	// A staged optional field (optional in the view) is compatible with a required stored field
+	// during the rollout period — suppress the kind discrepancy in that case.
+	if (
+		viewKind.identifier !== stored.kind &&
+		!(view.isStagedOptional !== false && stored.kind === FieldKinds.required.identifier)
+	) {
 		yield {
 			identifier,
 			fieldKey,

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

@@ -17,7 +17,7 @@ import type { TreeView } from "./tree.js";
 /**
  * An index that returns tree nodes given their associated identifiers.
  *
- * @alpha
+ * @beta
  */
 export type IdentifierIndex = TreeIndex<string, TreeNode>;
 
@@ -28,7 +28,7 @@ function isStringKey(key: TreeIndexKey): key is string {
 /**
  * Creates an {@link IdentifierIndex} for a given {@link TreeView}.
  *
- * @alpha
+ * @beta
  */
 export function createIdentifierIndex<TSchema extends ImplicitFieldSchema>(
 	view: TreeView<TSchema>,

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

@@ -66,6 +66,7 @@ export {
 	createCustomizedFluidFrameworkScopedFactory,
 } from "./schemaCreationUtilities.js";
 export {
+	deltaMarksToArrayOps,
 	getIdentifierFromNode,
 	getPropertyKeyFromStoredKey,
 	getStoredKey,
@@ -153,6 +154,19 @@ export {
 	TreeBeta,
 	type TreeChangeEventsBeta,
 } from "./treeBeta.js";
+export {
+	type ArrayNodeDeltaOp,
+	type ArrayNodeInsertOp,
+	type ArrayNodeRemoveOp,
+	type ArrayNodeRetainOp,
+	type ArrayNodeTreeChangedDeltaOp,
+	type ArrayNodeTreeChangedRetainOp,
+	type NodeChangedDataAlpha,
+	type NodeChangedDataDelta,
+	type NodeChangedDataProperties,
+	type NodeChangedDataTreeDelta,
+	type TreeChangeEventsAlpha,
+} from "./treeAlpha.js";
 export { createTreeIndex, type TreeIndexKey } from "./simpleTreeIndex.js";
 export {
 	createIdentifierIndex,

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

@@ -10,8 +10,6 @@ import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { TreeValue } from "../../core/index.js";
-// This import is required for intellisense in @link doc comments on mouseover in VSCode.
-// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
 import type { FlexTreeHydratedContextMinimal } from "../../feature-libraries/index.js";
 import {
 	type JsonCompatibleReadOnlyObject,

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

@@ -11,6 +11,7 @@ import {
 	type WithType,
 	normalizeAllowedTypes,
 	isTreeNode,
+	createSchemaUpgrade,
 } from "../core/index.js";
 // These imports prevent a large number of type references in the API reports from showing up as *_2.
 /* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */
@@ -18,7 +19,7 @@ import {
 	type FieldProps,
 	type FieldSchemaAlpha,
 	type FieldPropsAlpha,
-	type FieldKind,
+	FieldKind,
 	type ImplicitFieldSchema,
 	type InsertableTreeFieldFromImplicitField,
 	type FieldSchema,
@@ -29,6 +30,7 @@ import {
 import type { LeafSchema } from "../leafNodeSchema.js";
 import {
 	type ArrayNodeCustomizableSchema,
+	type ArrayNodeCustomizableSchemaAlpha,
 	arraySchema,
 	type MapNodeCustomizableSchema,
 	mapSchema,
@@ -142,6 +144,42 @@ export interface SchemaStaticsAlpha {
 		TCustomMetadata,
 		FieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }
 	>;
+	/**
+	 * Creates a field schema that is Optional in the view but behaves as Required in the stored schema
+	 * during the rollout period of an optional-field migration.
+	 *
+	 * @remarks
+	 * Use this to incrementally migrate a required field to optional without a coordinated deployment.
+	 * The migration path is:
+	 *
+	 * 1. Start with `sf.required(T)` — all clients require the field.
+	 * 2. Deploy `sf.stagedOptional(T)` — new clients can read documents where the field is present or absent, but the stored schema stays Required (so old clients are unaffected). Writing `undefined` is blocked at runtime.
+	 * 3. Deploy `sf.optional(T)` once all clients support the staged optional field — the stored schema becomes Optional and the field can be cleared.
+	 *
+	 * Analogous to {@link SchemaStaticsBeta.staged} for allowed types, but for field optionality.
+	 *
+	 * @param t - The types allowed under the field.
+	 * @param props - Optional properties to associate with the field.
+	 *
+	 * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+	 * See {@link FieldSchemaMetadata.custom}.
+	 */
+	readonly stagedOptional: <
+		const T extends ImplicitAllowedTypes,
+		const TCustomMetadata = unknown,
+	>(
+		t: T,
+		props?: Omit<
+			FieldPropsAlpha<TCustomMetadata>,
+			"defaultProvider" | "stagedOptionalUpgrade"
+		>,
+	) => FieldSchemaAlpha<
+		FieldKind.Optional,
+		T,
+		TCustomMetadata,
+		FieldPropsAlpha<TCustomMetadata>
+	>;
+
 	/**
 	 * {@link SchemaStaticsAlpha.withDefault} except tweaked to work better for recursive types.
 	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
@@ -224,10 +262,28 @@ const withDefault = <
 	);
 };
 
+const stagedOptional = <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+	t: T,
+	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider" | "stagedOptionalUpgrade">,
+): FieldSchemaAlpha<
+	FieldKind.Optional,
+	T,
+	TCustomMetadata,
+	FieldPropsAlpha<TCustomMetadata>
+> => {
+	return createFieldSchema(FieldKind.Optional, t, {
+		defaultProvider: getDefaultProvider(() => []),
+		...props,
+		stagedOptionalUpgrade: createSchemaUpgrade(),
+	});
+};
+
 const schemaStaticsAlpha: SchemaStaticsAlpha = {
 	withDefault,
 
 	withDefaultRecursive: withDefault as SchemaStaticsAlpha["withDefaultRecursive"],
+
+	stagedOptional,
 };
 
 /**
@@ -447,7 +503,17 @@ export class SchemaFactoryAlpha<
 	public static readonly withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;
 
 	/**
-	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
+	 * {@inheritdoc SchemaStaticsAlpha.stagedOptional}
+	 */
+	public readonly stagedOptional = schemaStaticsAlpha.stagedOptional;
+
+	/**
+	 * {@inheritdoc SchemaStaticsAlpha.stagedOptional}
+	 */
+	public static readonly stagedOptional = schemaStaticsAlpha.stagedOptional;
+
+	/**
+	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNodeAlpha}.
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
 	 * @param allowedTypes - The types that may appear as values in the map.
@@ -518,14 +584,24 @@ export class SchemaFactoryAlpha<
 		name: Name,
 		allowedTypes: T,
 		options?: NodeSchemaOptionsAlpha<TCustomMetadata>,
-	): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {
+	): ArrayNodeCustomizableSchemaAlpha<
+		ScopedSchemaName<TScope, Name>,
+		T,
+		true,
+		TCustomMetadata
+	> {
 		return arraySchema(
 			scoped<TScope, TName, Name>(this, name),
 			allowedTypes,
 			true,
 			true,
 			options ?? {},
-		);
+		) as unknown as ArrayNodeCustomizableSchemaAlpha<
+			ScopedSchemaName<TScope, Name>,
+			T,
+			true,
+			TCustomMetadata
+		>;
 	}
 
 	/**

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

@@ -39,7 +39,7 @@ import { treeNodeApi } from "./treeNodeApi.js";
  * @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
+ * @beta
  */
 export type TreeIndexKey = TreeLeafValue;
 
@@ -52,7 +52,7 @@ export type TreeIndexKey = TreeLeafValue;
  * @param getValue - given at least one {@link TreeNode}, returns an associated value
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
@@ -75,7 +75,7 @@ export function createTreeIndex<
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  * @param indexableSchema - a list of all the schema types that can be indexed
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
@@ -99,7 +99,7 @@ export function createTreeIndex<
  * @param getValue - given at least one {@link TreeNode}, returns an associated value
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
@@ -122,7 +122,7 @@ export function createTreeIndex<
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  * @param indexableSchema - a list of all the schema types that can be indexed
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,
@@ -140,7 +140,7 @@ export function createTreeIndex<
 /**
  * Creates a {@link TreeIndex} with a specified indexer.
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex<
 	TFieldSchema extends ImplicitFieldSchema,

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

@@ -5,17 +5,8 @@
 
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 
-import {
-	FluidClientVersion,
-	FormatValidatorNoOp,
-	type ICodecOptions,
-} from "../../codec/index.js";
-import { SchemaFormatVersion } from "../../core/index.js";
-import { makeSchemaCodec } from "../../feature-libraries/index.js";
-import type {
-	FormatV1,
-	// eslint-disable-next-line import-x/no-internal-modules
-} from "../../feature-libraries/schema-index/index.js";
+import { FormatValidatorNoOp, type ICodecOptions } from "../../codec/index.js";
+import { schemaCodecBuilder } from "../../feature-libraries/index.js";
 import type { JsonCompatible } from "../../util/index.js";
 import type { SchemaUpgrade } from "../core/index.js";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
@@ -62,8 +53,14 @@ export function extractPersistedSchema(
 	minVersionForCollab: MinimumVersionForCollab,
 	includeStaged: (upgrade: SchemaUpgrade) => boolean,
 ): JsonCompatible {
-	const stored = toStoredSchema(schema, { includeStaged });
-	const codec = makeSchemaCodec({ minVersionForCollab, jsonValidator: FormatValidatorNoOp });
+	const stored = toStoredSchema(schema, {
+		includeStaged,
+		includeStagedOptional: includeStaged,
+	});
+	const codec = schemaCodecBuilder.build({
+		minVersionForCollab,
+		jsonValidator: FormatValidatorNoOp,
+	});
 	return codec.encode(stored) as JsonCompatible;
 }
 
@@ -102,13 +99,8 @@ export function comparePersistedSchema(
 	view: ImplicitFieldSchema,
 	options: ICodecOptions,
 ): Omit<SchemaCompatibilityStatus, "canInitialize"> {
-	// 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, minVersionForCollab: FluidClientVersion.v2_0 },
-		SchemaFormatVersion.v1,
-	);
-	const stored = schemaCodec.decode(persisted as FormatV1);
+	const schemaCodec = schemaCodecBuilder.buildDecoder(options);
+	const stored = schemaCodec.decode(persisted);
 	const config = new TreeViewConfigurationAlpha({
 		schema: normalizeFieldSchema(view),
 	});

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

@@ -136,6 +136,8 @@ export interface ITreeAlpha extends ITree {
  * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork | creation of branches} and for those branches to later be {@link TreeBranch.merge | merged}.
  *
  * The branch associated directly with the {@link ITree | SharedTree} is the "main" branch, and all other branches fork (directly or transitively) from that main branch.
+ *
+ * See {@link TreeBranchAlpha} for additional APIs that are in an earlier stage of development.
  * @sealed @beta
  */
 export interface TreeBranch extends IDisposable {
@@ -352,6 +354,8 @@ export interface TreeBranchAlpha extends TreeBranch, TreeContextAlpha {
  * Application authors are encouraged to read {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/docs/user-facing/schema-evolution.md | schema-evolution.md}
  * and choose a schema compatibility policy that aligns with their application's needs.
  *
+ * See also {@link TreeViewAlpha}, {@link TreeViewBeta} and {@link TreeBranch} for additional APIs that are in earlier stages of development.
+ *
  * @privateRemarks
  * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.
  * Such approaches would make it discoverable that out of schema handling may need to be done.
@@ -559,7 +563,7 @@ export interface SchemaCompatibilityStatus {
  * Events for {@link TreeBranch}.
  * @sealed @alpha
  */
-export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied"> {
+export interface TreeBranchEvents {
 	/**
 	 * Fired when a change is made to the branch. Includes data about the change that is made which listeners
 	 * can use to filter on changes they care about (e.g. local vs. remote changes).
@@ -569,29 +573,12 @@ export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied">
 	 * this change is not revertible.
 	 */
 	changed(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;
-
-	/**
-	 * 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
-	 * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,
-	 * this commit is not revertible.
-	 */
-	commitApplied(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;
 }
 
 /**
  * Events for {@link TreeView}.
+ * @remarks
+ * See {@link TreeBranchEvents} for more events related to the underlying branch of the SharedTree.
  * @sealed @public
  */
 export interface TreeViewEvents {

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

@@ -0,0 +1,153 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { NodeKind, TreeNode, WithType } from "../core/index.js";
+
+import type { TreeChangeEventsBeta } from "./treeBeta.js";
+import type { TreeChangeEvents } from "./treeChangeEvents.js";
+import type { ArrayNodeDeltaOp, ArrayNodeTreeChangedDeltaOp } from "./treeNodeApi.js";
+export type {
+	ArrayNodeDeltaOp,
+	ArrayNodeInsertOp,
+	ArrayNodeRemoveOp,
+	ArrayNodeRetainOp,
+	ArrayNodeTreeChangedDeltaOp,
+	ArrayNodeTreeChangedRetainOp,
+} from "./treeNodeApi.js";
+
+/**
+ * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an object, map, or record node.
+ * @sealed @alpha
+ */
+export interface NodeChangedDataProperties<TNode extends TreeNode = TreeNode> {
+	/**
+	 * Lists all the properties which changed on the node.
+	 * @remarks
+	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
+	 *
+	 * The set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.
+	 */
+	readonly changedProperties: ReadonlySet<
+		// For Object nodes, strongly type with the property names from the schema:
+		TNode extends WithType<string, NodeKind.Object, infer TInfo>
+			? string & keyof TInfo
+			: string
+	>;
+}
+
+/**
+ * Data carried by the {@link TreeChangeEventsAlpha.nodeChanged} event for array nodes.
+ * @sealed @alpha
+ */
+export interface NodeChangedDataDelta {
+	/**
+	 * The sequential operations describing what changed in the array node.
+	 * @remarks
+	 * The value may be `undefined` when the document was updated in a way that required multiple
+	 * internal change passes in a single operation (for example, a data change combined with a
+	 * schema upgrade).
+	 *
+	 * See {@link ArrayNodeDeltaOp} for op semantics.
+	 */
+	readonly delta: readonly ArrayNodeDeltaOp[] | undefined;
+}
+
+/**
+ * Data carried by the {@link TreeChangeEventsAlpha.treeChanged} event for array nodes.
+ * @remarks
+ * Extends {@link NodeChangedDataDelta}: the retain ops in the delta additionally carry a
+ * {@link ArrayNodeTreeChangedRetainOp.subtreeChanged} flag indicating whether any descendant
+ * of the retained element changed.
+ * @sealed @alpha
+ */
+export interface NodeChangedDataTreeDelta {
+	/**
+	 * The sequential operations describing what changed in the array node,
+	 * including subtree-change information on retain ops.
+	 * @remarks
+	 * The value may be `undefined` when the document was updated in a way that required multiple
+	 * internal change passes in a single operation (for example, a data change combined with a
+	 * schema upgrade).
+	 *
+	 * See {@link ArrayNodeTreeChangedDeltaOp} for op semantics.
+	 */
+	readonly delta: readonly ArrayNodeTreeChangedDeltaOp[] | undefined;
+}
+
+/**
+ * The data passed to {@link TreeChangeEventsAlpha.nodeChanged} and, for array nodes,
+ * to {@link TreeChangeEventsAlpha.treeChanged}.
+ * @remarks
+ * - For array nodes: {@link NodeChangedDataDelta} (includes a {@link NodeChangedDataDelta.delta | delta} payload).
+ * - For object, map, and record nodes: {@link NodeChangedDataProperties} (includes {@link NodeChangedDataProperties.changedProperties | changedProperties}).
+ * - For a generic/unknown node type: the union of both.
+ * @alpha
+ */
+export type NodeChangedDataAlpha<TNode extends TreeNode = TreeNode> =
+	TNode extends WithType<string, NodeKind.Array>
+		? NodeChangedDataDelta
+		: TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>
+			? NodeChangedDataProperties<TNode>
+			: NodeChangedDataProperties<TNode> | NodeChangedDataDelta;
+
+/**
+ * Extension of {@link TreeChangeEvents} with a richer `nodeChanged` event and a
+ * delta-carrying `treeChanged` event for array nodes.
+ * @remarks
+ * Provides a `nodeChanged` event that includes a delta payload for array nodes and
+ * requires `changedProperties` for object, map, and record nodes.
+ * Also provides a `treeChanged` event that, for array nodes, carries a {@link NodeChangedDataDelta}
+ * payload describing both shallow and deep changes.
+ * For non-array nodes, the `treeChanged` signature is the same as the base event.
+ *
+ * Use via `TreeAlpha.on`.
+ * @sealed @alpha
+ */
+export interface TreeChangeEventsAlpha<TNode extends TreeNode = TreeNode>
+	extends TreeChangeEvents {
+	/**
+	 * Emitted when a shallow change occurs on this node, i.e., when the node's direct children change.
+	 *
+	 * @remarks
+	 * For array nodes: the event data includes a {@link NodeChangedDataDelta.delta | delta} payload
+	 * as a sequence of {@link ArrayNodeDeltaOp} values. Does not fire for deep changes (e.g. a
+	 * property of an array element changed without any shallow array change). Subscribe to
+	 * {@link TreeChangeEventsAlpha.treeChanged} on the array to receive a delta for those cases as well.
+	 *
+	 * For object, map, and record nodes: the event data includes
+	 * {@link NodeChangedDataProperties.changedProperties | changedProperties}.
+	 * @privateRemarks
+	 * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
+	 */
+	nodeChanged: (data: NodeChangedDataAlpha<TNode>) => void;
+
+	/**
+	 * Emitted when something in the subtree rooted at this node changes.
+	 *
+	 * @remarks
+	 * For array nodes: emitted when any change occurred within the array, including both
+	 * shallow changes (insert, remove, move) and deep changes (e.g. a property of an element
+	 * changed). The event data carries a {@link NodeChangedDataTreeDelta.delta | delta} payload
+	 * describing what changed. The delta uses {@link ArrayNodeTreeChangedRetainOp.subtreeChanged}
+	 * to flag elements that have deep changes, without describing the details of those deep changes.
+	 * To inspect deep changes, subscribe to `nodeChanged` or `treeChanged` on the individual
+	 * element nodes.
+	 *
+	 * When this array is nested inside another array, the outer array's `treeChanged` still
+	 * fires with a delta, but that delta only shows `subtreeChanged: true` for the element
+	 * position containing this inner array — it does not include the inner array's detailed
+	 * insert/remove/retain ops. To receive those detailed ops, subscribe to `treeChanged`
+	 * directly on the inner array.
+	 * Ancestor non-array nodes still receive the base (no-payload) `treeChanged` via normal
+	 * subtree propagation.
+	 *
+	 * For non-array nodes: same as the base {@link TreeChangeEvents.treeChanged}.
+	 * @privateRemarks
+	 * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
+	 */
+	treeChanged: TNode extends WithType<string, NodeKind.Array>
+		? (data: NodeChangedDataTreeDelta) => void
+		: TreeChangeEventsBeta<TNode>["treeChanged"];
+}

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

@@ -54,7 +54,7 @@ export interface NodeChangedData<TNode extends TreeNode = TreeNode> {
 	 * @remarks
 	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
 	 *
-	 * Set to `undefined` when the {@link NodeKind} does not support this feature (currently just ArrayNodes).
+	 * Not present when the {@link NodeKind} does not support this feature (currently just ArrayNodes).
 	 *
 	 * When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.
 	 */

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

@@ -6,6 +6,9 @@
 /**
  * A collection of events that can be emitted by a {@link TreeNode}.
  *
+ * @remarks
+ * Access these events via the {@link (Tree:variable)}'s {@link TreeNodeApi.on} method.
+ *
  * @privateRemarks
  * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
  * Probably have object node and map node specific APIs for this.
@@ -33,7 +36,7 @@ export interface TreeChangeEvents {
 	 *
 	 * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).
 	 *
-	 * - Array nodes define a change as when an element is added, removed, moved or replaced.
+	 * - Array nodes define a change as when an element is added, removed, moved, or replaced.
 	 *
 	 * - Map nodes define a change as when an entry is added, updated, or removed.
 	 *