@fluidframework/tree 2.10.0-304831 → 2.10.0-306579

package/src/feature-libraries/object-forest/objectForest.ts

@@ -33,7 +33,7 @@ import {
 	aboveRootPlaceholder,
 	deepCopyMapTree,
 } from "../../core/index.js";
-import { createEmitter } from "../../events/index.js";
+import { createEmitter, type Listenable } from "../../events/index.js";
 import {
 	assertNonNegativeSafeInteger,
 	assertValidIndex,
@@ -73,7 +73,8 @@ export class ObjectForest implements IEditableForest {
 	// All cursors that are in the "Current" state. Must be empty when editing.
 	public readonly currentCursors: Set<Cursor> = new Set();
 
-	private readonly events = createEmitter<ForestEvents>();
+	readonly #events = createEmitter<ForestEvents>();
+	public readonly events: Listenable<ForestEvents> = this.#events;
 
 	readonly #roots: MutableMapTree;
 	public get roots(): MapTree {
@@ -98,13 +99,6 @@ export class ObjectForest implements IEditableForest {
 		return this.roots.fields.size === 0;
 	}
 
-	public on<K extends keyof ForestEvents>(
-		eventName: K,
-		listener: ForestEvents[K],
-	): () => void {
-		return this.events.on(eventName, listener);
-	}
-
 	public clone(_: TreeStoredSchemaSubscription, anchors: AnchorSet): ObjectForest {
 		return new ObjectForest(anchors, this.additionalAsserts, this.roots);
 	}
@@ -133,7 +127,7 @@ export class ObjectForest implements IEditableForest {
 		 * This is required for each change since there may be app facing change event handlers which create cursors.
 		 */
 		const preEdit = (): void => {
-			this.events.emit("beforeChange");
+			this.#events.emit("beforeChange");
 			assert(
 				this.currentCursors.has(cursor),
 				0x995 /* missing visitor cursor while editing */,
@@ -168,7 +162,7 @@ export class ObjectForest implements IEditableForest {
 			public create(content: ProtoNodes, destination: FieldKey): void {
 				preEdit();
 				this.forest.add(content, destination);
-				this.forest.events.emit("afterRootFieldCreated", destination);
+				this.forest.#events.emit("afterRootFieldCreated", destination);
 			}
 			public attach(source: FieldKey, count: number, destination: PlaceIndex): void {
 				preEdit();

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

@@ -52,7 +52,7 @@ export class SchemaSummarizer implements Summarizable {
 		collabWindow: CollabWindow,
 	) {
 		this.codec = makeSchemaCodec(options);
-		this.schema.on("afterSchemaChange", () => {
+		this.schema.events.on("afterSchemaChange", () => {
 			// Invalidate the cache, as we need to regenerate the blob if the schema changes
 			// We are assuming that schema changes from remote ops are valid, as we are in a summarization context.
 			this.schemaIndexLastChangedSeq = collabWindow.getCurrentSeq();

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

@@ -582,7 +582,7 @@ export class ComposeQueue {
 		}
 	}
 
-	private dequeueBase(length: number = Infinity): ComposeMarks {
+	private dequeueBase(length: number = Number.POSITIVE_INFINITY): ComposeMarks {
 		const baseMark = this.baseMarks.dequeueUpTo(length);
 		const movedChanges = getMovedChangesFromMark(this.moveEffects, baseMark);
 		if (movedChanges !== undefined) {
@@ -593,7 +593,7 @@ export class ComposeQueue {
 		return { baseMark, newMark };
 	}
 
-	private dequeueNew(length: number = Infinity): ComposeMarks {
+	private dequeueNew(length: number = Number.POSITIVE_INFINITY): ComposeMarks {
 		const newMark = this.newMarks.dequeueUpTo(length);
 		const baseMark = createNoopMark(newMark.count, undefined, getInputCellId(newMark));
 

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

@@ -42,7 +42,7 @@ export class MarkListFactory {
 		if (prev !== undefined && prev.type === mark.type) {
 			const merged = tryMergeMarks(prev, mark);
 			if (merged !== undefined) {
-				this.list.splice(this.list.length - 1, 1, merged);
+				this.list.splice(-1, 1, merged);
 				return;
 			}
 		}

package/src/index.ts

@@ -170,6 +170,21 @@ export {
 	getJsonSchema,
 	type LazyItem,
 	type Unenforced,
+	type SimpleNodeSchemaBase,
+	type SimpleTreeSchema,
+	type SimpleNodeSchema,
+	type SimpleFieldSchema,
+	type SimpleLeafNodeSchema,
+	type SimpleMapNodeSchema,
+	type SimpleArrayNodeSchema,
+	type SimpleObjectNodeSchema,
+	normalizeAllowedTypes,
+	getSimpleSchema,
+	numberSchema,
+	stringSchema,
+	booleanSchema,
+	handleSchema,
+	nullSchema,
 	type ReadonlyArrayNode,
 	type InsertableTreeNodeFromAllowedTypes,
 	type Input,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.10.0-304831";
+export const pkgVersion = "2.10.0-306579";

package/src/shared-tree/schematizingTreeView.ts

@@ -297,7 +297,7 @@ export class SchematizingSimpleTreeView<
 				new HydratedContext(this.rootFieldSchema.allowedTypeSet, view.context),
 			);
 
-			const unregister = this.checkout.storedSchema.on("afterSchemaChange", () => {
+			const unregister = this.checkout.storedSchema.events.on("afterSchemaChange", () => {
 				unregister();
 				this.unregisterCallbacks.delete(unregister);
 				view[disposeSymbol]();
@@ -307,7 +307,7 @@ export class SchematizingSimpleTreeView<
 			this.view = undefined;
 			this.checkout.forest.anchors.slots.delete(SimpleContextSlot);
 
-			const unregister = this.checkout.storedSchema.on("afterSchemaChange", () => {
+			const unregister = this.checkout.storedSchema.events.on("afterSchemaChange", () => {
 				unregister();
 				this.unregisterCallbacks.delete(unregister);
 				this.update();

package/src/shared-tree/treeApi.ts

@@ -478,10 +478,10 @@ function runTransactionInCheckout<TResult>(
 	let result: ReturnType<typeof transaction>;
 	try {
 		result = transaction();
-	} catch (e) {
+	} catch (error) {
 		// If the transaction has an unhandled error, abort and rollback the transaction but continue to propagate the error.
 		checkout.transaction.abort();
-		throw e;
+		throw error;
 	}
 
 	if (result === rollback) {

package/src/shared-tree/treeCheckout.ts

@@ -444,15 +444,15 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		private readonly breaker: Breakable = new Breakable("TreeCheckout"),
 	) {
 		// when a transaction is started, take a snapshot of the current state of removed roots
-		_branch.on("transactionStarted", () => {
+		_branch.events.on("transactionStarted", () => {
 			this.removedRootsSnapshots.push(this.removedRoots.clone());
 		});
 		// when a transaction is committed, the latest snapshot of removed roots can be discarded
-		_branch.on("transactionCommitted", () => {
+		_branch.events.on("transactionCommitted", () => {
 			this.removedRootsSnapshots.pop();
 		});
 		// after a transaction is rolled back, revert removed roots back to the latest snapshot
-		_branch.on("transactionRolledBack", () => {
+		_branch.events.on("transactionRolledBack", () => {
 			const snapshot = this.removedRootsSnapshots.pop();
 			assert(snapshot !== undefined, 0x9ae /* a snapshot for removed roots does not exist */);
 			this.removedRoots = snapshot;
@@ -462,7 +462,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		// For example, a bug in the editor might produce a malformed change object and thus applying the change to the forest will throw an error.
 		// In such a case we will crash here, preventing the change from being added to the commit graph, and preventing `afterChange` from firing.
 		// One important consequence of this is that we will not submit the op containing the invalid change, since op submissions happens in response to `afterChange`.
-		_branch.on("beforeChange", (event) => {
+		_branch.events.on("beforeChange", (event) => {
 			if (event.change !== undefined) {
 				const revision =
 					event.type === "replace"
@@ -509,7 +509,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 				}
 			}
 		});
-		_branch.on("afterChange", (event) => {
+		_branch.events.on("afterChange", (event) => {
 			// The following logic allows revertibles to be generated for the change.
 			// Currently only appends (including merges) and transaction commits are supported.
 			if (!_branch.isTransacting()) {
@@ -590,7 +590,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 
 		// When the branch is trimmed, we can garbage collect any repair data whose latest relevant revision is one of the
 		// trimmed revisions.
-		_branch.on("ancestryTrimmed", (revisions) => {
+		_branch.events.on("ancestryTrimmed", (revisions) => {
 			this.withCombinedVisitor((visitor) => {
 				revisions.forEach((revision) => {
 					// get all the roots last created or used by the revision
@@ -653,7 +653,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	}
 
 	public get rootEvents(): Listenable<AnchorSetRootEvents> {
-		return this.forest.anchors;
+		return this.forest.anchors.events;
 	}
 
 	public get editor(): ISharedTreeEditor {

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

@@ -21,7 +21,7 @@ import {
 	tagRollbackInverse,
 	type RebaseStatsWithDuration,
 } from "../core/index.js";
-import { EventEmitter, type Listenable } from "../events/index.js";
+import { createEmitter, type Listenable } from "../events/index.js";
 
 import { TransactionStack } from "./transactionStack.js";
 import { fail } from "../util/index.js";
@@ -175,10 +175,9 @@ export interface BranchTrimmingEvents {
 /**
  * A branch of changes that can be applied to a SharedTree.
  */
-export class SharedTreeBranch<
-	TEditor extends ChangeFamilyEditor,
-	TChange,
-> extends EventEmitter<SharedTreeBranchEvents<TEditor, TChange>> {
+export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
+	readonly #events = createEmitter<SharedTreeBranchEvents<TEditor, TChange>>();
+	public readonly events: Listenable<SharedTreeBranchEvents<TEditor, TChange>> = this.#events;
 	public readonly editor: TEditor;
 	private readonly transactions = new TransactionStack();
 	/**
@@ -222,12 +221,11 @@ export class SharedTreeBranch<
 			keyof RebaseStatsWithDuration
 		>,
 	) {
-		super();
 		this.editor = this.changeFamily.buildEditor(mintRevisionTag, (change) =>
 			this.apply(change),
 		);
 		this.unsubscribeBranchTrimmer = branchTrimmer?.on("ancestryTrimmed", (commit) => {
-			this.emit("ancestryTrimmed", commit);
+			this.#events.emit("ancestryTrimmed", commit);
 		});
 	}
 
@@ -267,9 +265,9 @@ export class SharedTreeBranch<
 			newCommits: [newHead],
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = newHead;
-		this.emit("afterChange", changeEvent);
+		this.#events.emit("afterChange", changeEvent);
 		return [taggedChange.change, newHead];
 	}
 
@@ -290,7 +288,7 @@ export class SharedTreeBranch<
 		const onDisposeUnSubscribes: (() => void)[] = [];
 		const onForkUnSubscribe = onForkTransitive(this, (fork) => {
 			forks.add(fork);
-			onDisposeUnSubscribes.push(fork.on("dispose", () => forks.delete(fork)));
+			onDisposeUnSubscribes.push(fork.events.on("dispose", () => forks.delete(fork)));
 		});
 		this.transactions.push(this.head.revision, () => {
 			forks.forEach((fork) => fork.dispose());
@@ -298,7 +296,7 @@ export class SharedTreeBranch<
 			onForkUnSubscribe();
 		});
 		this.editor.enterTransaction();
-		this.emit("transactionStarted", this.transactions.size === 1);
+		this.#events.emit("transactionStarted", this.transactions.size === 1);
 	}
 
 	/**
@@ -315,7 +313,7 @@ export class SharedTreeBranch<
 		const [startCommit, commits] = this.popTransaction();
 		this.editor.exitTransaction();
 
-		this.emit("transactionCommitted", this.transactions.size === 0);
+		this.#events.emit("transactionCommitted", this.transactions.size === 0);
 		if (commits.length === 0) {
 			return undefined;
 		}
@@ -336,9 +334,9 @@ export class SharedTreeBranch<
 			newCommits: [newHead],
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = newHead;
-		this.emit("afterChange", changeEvent);
+		this.#events.emit("afterChange", changeEvent);
 		return [commits, newHead];
 	}
 
@@ -356,9 +354,9 @@ export class SharedTreeBranch<
 		const [startCommit, commits] = this.popTransaction();
 		this.editor.exitTransaction();
 
-		this.emit("transactionAborted", this.transactions.size === 0);
+		this.#events.emit("transactionAborted", this.transactions.size === 0);
 		if (commits.length === 0) {
-			this.emit("transactionRolledBack", this.transactions.size === 0);
+			this.#events.emit("transactionRolledBack", this.transactions.size === 0);
 			return [undefined, []];
 		}
 
@@ -384,10 +382,10 @@ export class SharedTreeBranch<
 			removedCommits: commits,
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = startCommit;
-		this.emit("afterChange", changeEvent);
-		this.emit("transactionRolledBack", this.transactions.size === 0);
+		this.#events.emit("afterChange", changeEvent);
+		this.#events.emit("transactionRolledBack", this.transactions.size === 0);
 		return [change, commits];
 	}
 
@@ -435,7 +433,7 @@ export class SharedTreeBranch<
 			this.mintRevisionTag,
 			this.branchTrimmer,
 		);
-		this.emit("fork", fork);
+		this.#events.emit("fork", fork);
 		return fork;
 	}
 
@@ -483,9 +481,9 @@ export class SharedTreeBranch<
 			newCommits,
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = newSourceHead;
-		this.emit("afterChange", changeEvent);
+		this.#events.emit("afterChange", changeEvent);
 		return rebaseResult;
 	}
 
@@ -529,9 +527,9 @@ export class SharedTreeBranch<
 			newCommits: sourceCommits,
 		} as const;
 
-		this.emit("beforeChange", changeEvent);
+		this.#events.emit("beforeChange", changeEvent);
 		this.head = rebaseResult.newSourceHead;
-		this.emit("afterChange", changeEvent);
+		this.#events.emit("afterChange", changeEvent);
 		return [change, sourceCommits];
 	}
 
@@ -585,7 +583,7 @@ export class SharedTreeBranch<
 		this.unsubscribeBranchTrimmer?.();
 
 		this.disposed = true;
-		this.emit("dispose");
+		this.#events.emit("dispose");
 	}
 
 	private assertNotDisposed(): void {
@@ -594,20 +592,22 @@ export class SharedTreeBranch<
 }
 
 /**
- * Registers an event listener that fires when the given forkable object forks.
+ * Registers an event listener that fires when the given branch forks.
  * The listener will also fire when any of those forks fork, and when those forks of forks fork, and so on.
- * @param forkable - an object that emits an event when it is forked
+ * @param branch - the branch that will be listened to for forks
  * @param onFork - the fork event listener
  * @returns a function which when called will deregister all registrations (including transitive) created by this function.
  * The deregister function has undefined behavior if called more than once.
  */
-export function onForkTransitive<T extends Listenable<{ fork: (t: T) => void }>>(
-	forkable: T,
+// Branches are invariant over TChange
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function onForkTransitive<T extends SharedTreeBranch<ChangeFamilyEditor, any>>(
+	branch: T,
 	onFork: (fork: T) => void,
 ): () => void {
 	const offs: (() => void)[] = [];
 	offs.push(
-		forkable.on("fork", (fork) => {
+		branch.events.on("fork", (fork: T) => {
 			offs.push(onForkTransitive(fork, onFork));
 			onFork(fork);
 		}),

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

@@ -191,7 +191,7 @@ export class EditManager<
 			this.telemetryEventBatcher,
 		);
 
-		this.localBranch.on("afterChange", (event) => {
+		this.localBranch.events.on("afterChange", (event) => {
 			if (event.type === "append") {
 				for (const commit of event.newCommits) {
 					this.localCommits.push(commit);
@@ -223,19 +223,19 @@ export class EditManager<
 	private registerBranch(branch: SharedTreeBranch<TEditor, TChangeset>): void {
 		this.trackBranch(branch);
 		// Whenever the branch is rebased, update our record of its base trunk commit
-		const offBeforeRebase = branch.on("beforeChange", (args) => {
+		const offBeforeRebase = branch.events.on("beforeChange", (args) => {
 			if (args.type === "replace" && getChangeReplaceType(args) === "rebase") {
 				this.untrackBranch(branch);
 			}
 		});
-		const offAfterRebase = branch.on("afterChange", (args) => {
+		const offAfterRebase = branch.events.on("afterChange", (args) => {
 			if (args.type === "replace" && getChangeReplaceType(args) === "rebase") {
 				this.trackBranch(branch);
 				this.trimTrunk();
 			}
 		});
 		// When the branch is disposed, update our branch set and trim the trunk
-		const offDispose = branch.on("dispose", () => {
+		const offDispose = branch.events.on("dispose", () => {
 			this.untrackBranch(branch);
 			this.trimTrunk();
 			offBeforeRebase();

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

@@ -183,16 +183,16 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			this.mintRevisionTag,
 			rebaseLogger,
 		);
-		this.editManager.localBranch.on("transactionStarted", () => {
+		this.editManager.localBranch.events.on("transactionStarted", () => {
 			this.commitEnricher.startNewTransaction();
 		});
-		this.editManager.localBranch.on("transactionAborted", () => {
+		this.editManager.localBranch.events.on("transactionAborted", () => {
 			this.commitEnricher.abortCurrentTransaction();
 		});
-		this.editManager.localBranch.on("transactionCommitted", () => {
+		this.editManager.localBranch.events.on("transactionCommitted", () => {
 			this.commitEnricher.commitCurrentTransaction();
 		});
-		this.editManager.localBranch.on("beforeChange", (change) => {
+		this.editManager.localBranch.events.on("beforeChange", (change) => {
 			// Ensure that any previously prepared commits that have not been sent are purged.
 			this.commitEnricher.purgePreparedCommits();
 			if (this.detachedRevision !== undefined) {
@@ -219,7 +219,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				this.commitEnricher.prepareCommit(change.newCommits[0] ?? oob(), true);
 			}
 		});
-		this.editManager.localBranch.on("afterChange", (change) => {
+		this.editManager.localBranch.events.on("afterChange", (change) => {
 			if (this.getLocalBranch().isTransacting()) {
 				// We do not submit ops for changes that are part of a transaction.
 				return;

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

@@ -63,6 +63,8 @@ const simpleSchemaCache = new WeakMap<TreeNodeSchema, SimpleTreeSchema>();
  *
  * @privateRemarks In the future, we may wish to move this to a more discoverable API location.
  * For now, while still an experimental API, it is surfaced as a free function.
+ *
+ * @internal
  */
 export function getSimpleSchema(schema: ImplicitFieldSchema): SimpleTreeSchema {
 	return getOrCreate(simpleSchemaCache, schema, () => toSimpleTreeSchema(schema));

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

@@ -29,7 +29,16 @@ export {
 } from "./schemaCreationUtilities.js";
 export { treeNodeApi, type TreeNodeApi, tryGetSchema } from "./treeNodeApi.js";
 export { createFromInsertable, cursorFromInsertable, createFromCursor } from "./create.js";
-export type { SimpleTreeSchema } from "./simpleSchema.js";
+export type {
+	SimpleTreeSchema,
+	SimpleNodeSchema,
+	SimpleFieldSchema,
+	SimpleLeafNodeSchema,
+	SimpleMapNodeSchema,
+	SimpleArrayNodeSchema,
+	SimpleObjectNodeSchema,
+	SimpleNodeSchemaBase,
+} from "./simpleSchema.js";
 export {
 	type JsonSchemaId,
 	type JsonSchemaType,

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

@@ -216,19 +216,45 @@ export class SchemaFactory<
 	private readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();
 
 	/**
-	 * Construct a SchemaFactory with a given scope.
+	 * Construct a SchemaFactory with a given {@link SchemaFactory.scope|scope}.
 	 * @remarks
-	 * There are no restrictions on mixing schema from different schema factories:
-	 * this is encouraged when a single schema references schema from different libraries.
-	 * If each library exporting schema picks its own globally unique scope for its SchemaFactory,
-	 * then all schema an application might depend on, directly or transitively,
-	 * will end up with a unique fully qualified name which is required to refer to it in persisted data and errors.
-	 *
-	 * @param scope - Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.
-	 * Use of [Reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) or a UUIDv4 is recommended to avoid collisions.
-	 * You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.
+	 * There are no restrictions on mixing schema from different schema factories.
+	 * Typically each library will create one or more SchemaFactories and use them to define its schema.
 	 */
-	public constructor(public readonly scope: TScope) {}
+	public constructor(
+		/**
+		 * Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.
+		 *
+		 * @remarks
+		 * Generally each independently developed library
+		 * (possibly a package, but could also be part of a package or multiple packages developed together)
+		 * should get its own unique `scope`.
+		 * Then each schema in the library get a name which is unique within the library.
+		 * The scope and name are joined (with a period) to form the {@link TreeNodeSchemaCore.identifier|schema identifier}.
+		 * Following this pattern allows a single application to depend on multiple libraries which define their own schema, and use them together in a single tree without risk of collisions.
+		 * If a library logically contains sub-libraries with their own schema, they can be given a scope nested inside the parent scope, such as "ParentScope.ChildScope".
+		 *
+		 * To avoid collisions between the scopes of libraries
+		 * it is recommended that the libraries use {@link https://en.wikipedia.org/wiki/Reverse_domain_name_notation | Reverse domain name notation} or a UUIDv4 for their scope.
+		 * If this pattern is followed, application can safely use third party libraries without risk of the schema in them colliding.
+		 *
+		 * You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.
+		 *
+		 * @example
+		 * Fluid Framework follows this pattern, placing the schema for the built in leaf types in the `com.fluidframework.leaf` scope.
+		 * If Fluid Framework publishes more schema in the future, they would be under some other `com.fluidframework` scope.
+		 * This ensures that any schema defined by any other library will not conflict with Fluid Framework's schema
+		 * as long as the library uses the recommended patterns for how to scope its schema..
+		 *
+		 * @example
+		 * A library could generate a random UUIDv4, like `242c4397-49ed-47e6-8dd0-d5c3bc31778b` and use that as the scope.
+		 * Note: do not use this UUID: a new one must be randomly generated when needed to ensure collision resistance.
+		 * ```typescript
+		 * const factory = new SchemaFactory("242c4397-49ed-47e6-8dd0-d5c3bc31778b");
+		 * ```
+		 */
+		public readonly scope: TScope,
+	) {}
 
 	private scoped<Name extends TName | string>(name: Name): ScopedSchemaName<TScope, Name> {
 		return (

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

@@ -5,11 +5,12 @@
 
 import type { ValueSchema } from "../../core/index.js";
 import type { NodeKind } from "../core/index.js";
-import type { FieldKind } from "../schemaTypes.js";
+import type { FieldKind, FieldSchemaMetadata } from "../schemaTypes.js";
 
 /**
  * Base interface for all {@link SimpleNodeSchema} implementations.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
@@ -24,6 +25,7 @@ export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
 /**
  * A {@link SimpleNodeSchema} for an object node.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Object> {
@@ -36,6 +38,7 @@ export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Ob
 /**
  * A {@link SimpleNodeSchema} for an array node.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleArrayNodeSchema extends SimpleNodeSchemaBase<NodeKind.Array> {
@@ -51,6 +54,7 @@ export interface SimpleArrayNodeSchema extends SimpleNodeSchemaBase<NodeKind.Arr
 /**
  * A {@link SimpleNodeSchema} for a map node.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleMapNodeSchema extends SimpleNodeSchemaBase<NodeKind.Map> {
@@ -66,6 +70,7 @@ export interface SimpleMapNodeSchema extends SimpleNodeSchemaBase<NodeKind.Map>
 /**
  * A {@link SimpleNodeSchema} for a leaf node.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleLeafNodeSchema extends SimpleNodeSchemaBase<NodeKind.Leaf> {
@@ -81,6 +86,8 @@ export interface SimpleLeafNodeSchema extends SimpleNodeSchemaBase<NodeKind.Leaf
  * @remarks This definition is incomplete, and references child types by identifiers.
  * To be useful, this generally needs to be used as a part of a complete {@link SimpleTreeSchema}, which
  * contains backing {@link SimpleTreeSchema.definitions} for each referenced identifier.
+ *
+ * @internal
  */
 export type SimpleNodeSchema =
 	| SimpleLeafNodeSchema
@@ -95,6 +102,7 @@ export type SimpleNodeSchema =
  * To be useful, this generally needs to be used as a part of a complete {@link SimpleTreeSchema}, which
  * contains backing {@link SimpleTreeSchema.definitions} for each referenced identifier.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleFieldSchema {
@@ -112,9 +120,9 @@ export interface SimpleFieldSchema {
 	readonly allowedTypes: ReadonlySet<string>;
 
 	/**
-	 * {@inheritDoc FieldSchemaMetadata.description}
+	 * {@inheritDoc FieldSchemaMetadata}
 	 */
-	readonly description?: string | undefined;
+	readonly metadata?: FieldSchemaMetadata | undefined;
 }
 
 /**
@@ -123,6 +131,7 @@ export interface SimpleFieldSchema {
  * @remarks Contains the complete set of schema {@link SimpleTreeSchema.definitions} required to resolve references,
  * which are represented inline with identifiers.
  *
+ * @internal
  * @sealed
  */
 export interface SimpleTreeSchema extends SimpleFieldSchema {

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

@@ -150,8 +150,8 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 					};
 
 		// Don't include "description" property at all if it's not present in the input.
-		if (value.description !== undefined) {
-			output.description = value.description;
+		if (value.metadata?.description !== undefined) {
+			output.description = value.metadata.description;
 		}
 
 		properties[key] = output;

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

@@ -168,7 +168,7 @@ export const treeNodeApi: TreeNodeApi = {
 			case "nodeChanged": {
 				const nodeSchema = kernel.schema;
 				if (isObjectNodeSchema(nodeSchema)) {
-					return kernel.on("childrenChangedAfterBatch", ({ changedFields }) => {
+					return kernel.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
 						const changedProperties = new Set(
 							Array.from(
 								changedFields,
@@ -180,17 +180,17 @@ export const treeNodeApi: TreeNodeApi = {
 						listener({ changedProperties });
 					});
 				} else if (nodeSchema.kind === NodeKind.Array) {
-					return kernel.on("childrenChangedAfterBatch", () => {
+					return kernel.events.on("childrenChangedAfterBatch", () => {
 						listener({ changedProperties: undefined });
 					});
 				} else {
-					return kernel.on("childrenChangedAfterBatch", ({ changedFields }) => {
+					return kernel.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
 						listener({ changedProperties: changedFields });
 					});
 				}
 			}
 			case "treeChanged": {
-				return kernel.on("subtreeChangedAfterBatch", () => listener({}));
+				return kernel.events.on("subtreeChangedAfterBatch", () => listener({}));
 			}
 			default:
 				throw new UsageError(`No event named ${JSON.stringify(eventName)}.`);