@fluidframework/tree 2.53.0-350190 → 2.53.1

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

@@ -19,8 +19,10 @@ import type {
 } from "../../core/index.js";
 import { type JsonCompatibleReadOnly, type Mutable, brand } from "../../util/index.js";
 import { makeChangeAtomIdCodec } from "../changeAtomIdCodec.js";
-import type { FieldChangeEncodingContext } from "../index.js";
-import { EncodedNodeChangeset } from "../modular-schema/index.js";
+import {
+	EncodedNodeChangeset,
+	type FieldChangeEncodingContext,
+} from "../modular-schema/index.js";
 
 import { Changeset as ChangesetSchema, type Encoded } from "./formatV2.js";
 import type { SequenceCodecHelpers } from "./helperTypes.js";

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

@@ -12,8 +12,10 @@ import type {
 	RevisionTag,
 } from "../../core/index.js";
 import type { JsonCompatibleReadOnly } from "../../util/index.js";
-import type { FieldChangeEncodingContext } from "../index.js";
-import { EncodedNodeChangeset } from "../modular-schema/index.js";
+import {
+	EncodedNodeChangeset,
+	type FieldChangeEncodingContext,
+} from "../modular-schema/index.js";
 
 import { Changeset as ChangesetSchema, type Encoded } from "./formatV3.js";
 import { makeV2CodecHelpers } from "./sequenceFieldCodecV2.js";

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

@@ -9,7 +9,7 @@ import type {
 	EncodedRevisionTag,
 	RevisionTag,
 } from "../../core/index.js";
-import type { FieldChangeEncodingContext } from "../index.js";
+import type { FieldChangeEncodingContext } from "../modular-schema/index.js";
 
 import { makeV1Codec } from "./sequenceFieldCodecV1.js";
 import { makeV2Codec } from "./sequenceFieldCodecV2.js";

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

@@ -4,7 +4,7 @@
  */
 
 import type { ChangeAtomId, ChangesetLocalId, RevisionTag } from "../../core/index.js";
-import type { NodeId } from "../index.js";
+import type { NodeId } from "../modular-schema/index.js";
 
 export type CellCount = number;
 

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.53.0-350190";
+export const pkgVersion = "2.53.1";

package/src/shared-tree/independentView.ts

@@ -42,7 +42,7 @@ import {
 } from "./sharedTree.js";
 import { createTreeCheckout } from "./treeCheckout.js";
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
-import { initialize } from "./schematizeTree.js";
+import { initialize, initializerFromChunk } from "./schematizeTree.js";
 
 /**
  * Create an uninitialized {@link TreeView} that is not tied to any {@link ITree} instance.
@@ -152,7 +152,11 @@ export function independentInitializedViewInternal<const TSchema extends Implici
 		breaker,
 	});
 
-	initialize(checkout, { schema, initialTree: rootFieldCursor });
+	initialize(
+		checkout,
+		schema,
+		initializerFromChunk(checkout, () => checkout.forest.chunkField(rootFieldCursor)),
+	);
 	return new SchematizingSimpleTreeView<TSchema>(
 		checkout,
 		config,

package/src/shared-tree/index.ts

@@ -35,8 +35,6 @@ export {
 	type TreeBranchFork,
 } from "./treeCheckout.js";
 
-export { type TreeStoredContent } from "./schematizeTree.js";
-
 export { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 
 export type {

package/src/shared-tree/schematizeTree.ts

@@ -3,240 +3,124 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 
-import {
-	CursorLocationType,
-	type ITreeCursorSynchronous,
-	type TreeStoredSchema,
-	rootFieldKey,
-	schemaDataIsEmpty,
-} from "../core/index.js";
+import { type TreeStoredSchema, rootFieldKey, schemaDataIsEmpty } from "../core/index.js";
 import {
 	FieldKinds,
 	allowsRepoSuperset,
-	cursorForMapTreeField,
 	defaultSchemaPolicy,
-	mapTreeFromCursor,
+	type IDefaultEditBuilder,
+	type TreeChunk,
 } from "../feature-libraries/index.js";
-import { toUpgradeSchema, type SchemaCompatibilityTester } from "../simple-tree/index.js";
-import { isReadonlyArray } from "../util/index.js";
 
 import type { ITreeCheckout } from "./treeCheckout.js";
 
+export function canInitialize(checkout: ITreeCheckout): boolean {
+	// Check for empty.
+	return checkout.forest.isEmpty && schemaDataIsEmpty(checkout.storedSchema);
+}
+
 /**
- * Modify `storedSchema` and invoke `setInitialTree` when it's time to set the tree content.
- *
- * Requires `storedSchema` to be in its default/empty state.
- *
- * This is done in such a way that if the content (implicitly assumed to start empty)
- * is never out of schema.
- * This means that if the root field of the new schema requires content (like a value field),
- * a temporary intermediate schema is used so the initial empty state is not out of schema.
+ * Initialize a checkout with a schema and tree content.
+ * This function should only be called when the tree is uninitialized (no schema or content).
  *
- * Since this makes multiple changes, callers may want to wrap it in a transaction.
+ * @param checkout - The tree checkout to initialize.
+ * @param newSchema - The new schema to apply.
+ * @param contentFactory - A function that sets the initial tree content.
+ * Invoked after a schema containing all nodes from newSchema is applied.
+ * Note that the final root field schema may not have been applied yet: if the root is required, it will be optional at this time
+ * (so the root being empty before the insertion is not out of schema).
+ * @remarks
+ * If `newSchema` is not compatible with the empty tree, this function handles it using an intermediate schema
+ * which supports the empty tree as well as the final tree content.
+ * @privateRemarks
+ * This takes in a checkout using a subset of the checkout interface to enable easier unit testing.
  */
-export function initializeContent(
-	schemaRepository: {
-		storedSchema: ITreeCheckout["storedSchema"];
-		updateSchema: ITreeCheckout["updateSchema"];
-	},
+export function initialize(
+	checkout: Pick<ITreeCheckout, "storedSchema" | "updateSchema">,
 	newSchema: TreeStoredSchema,
 	setInitialTree: () => void,
 ): void {
 	assert(
-		schemaDataIsEmpty(schemaRepository.storedSchema),
+		schemaDataIsEmpty(checkout.storedSchema),
 		0x743 /* cannot initialize after a schema is set */,
 	);
 
-	const rootSchema = newSchema.rootFieldSchema;
-	const rootKind = rootSchema.kind;
-
 	// To keep the data in schema during the update, first define a schema that tolerates the current (empty) tree as well as the final (initial) tree.
-	let incrementalSchemaUpdate: TreeStoredSchema;
-	if (
-		rootKind === FieldKinds.sequence.identifier ||
-		rootKind === FieldKinds.optional.identifier
-	) {
-		// These kinds are known to tolerate empty, so use the schema as is:
-		incrementalSchemaUpdate = newSchema;
-	} else {
-		assert(rootKind === FieldKinds.required.identifier, 0x5c8 /* Unexpected kind */);
-		// Replace value kind with optional kind in root field schema:
-		incrementalSchemaUpdate = {
-			nodeSchema: newSchema.nodeSchema,
-			rootFieldSchema: {
-				kind: FieldKinds.optional.identifier,
-				types: rootSchema.types,
-				persistedMetadata: rootSchema.persistedMetadata,
-			},
-		};
+	let intermediateSchema: TreeStoredSchema;
+	{
+		const rootSchema = newSchema.rootFieldSchema;
+		const rootKind = rootSchema.kind;
+		if (
+			rootKind === FieldKinds.sequence.identifier ||
+			rootKind === FieldKinds.optional.identifier
+		) {
+			// These kinds are known to tolerate empty, so use the schema as is:
+			intermediateSchema = newSchema;
+		} else {
+			assert(rootKind === FieldKinds.required.identifier, 0x5c8 /* Unexpected kind */);
+			// Replace value kind with optional kind in root field schema:
+			intermediateSchema = {
+				nodeSchema: newSchema.nodeSchema,
+				rootFieldSchema: {
+					kind: FieldKinds.optional.identifier,
+					types: rootSchema.types,
+					persistedMetadata: rootSchema.persistedMetadata,
+				},
+			};
+		}
 	}
 
 	assert(
-		allowsRepoSuperset(defaultSchemaPolicy, newSchema, incrementalSchemaUpdate),
+		allowsRepoSuperset(defaultSchemaPolicy, newSchema, intermediateSchema),
 		0x5c9 /* Incremental Schema during update should allow a superset of the final schema */,
 	);
-	// Update to intermediate schema
-	schemaRepository.updateSchema(incrementalSchemaUpdate);
-	// Insert initial tree
+
+	checkout.updateSchema(intermediateSchema);
 	setInitialTree();
 
 	// If intermediate schema is not final desired schema, update to the final schema:
-	if (incrementalSchemaUpdate !== newSchema) {
+	if (intermediateSchema !== newSchema) {
 		// This makes the root more strict, so set allowNonSupersetSchema to true.
-		schemaRepository.updateSchema(newSchema, true);
+		checkout.updateSchema(newSchema, true);
 	}
 }
 
-export enum UpdateType {
-	/**
-	 * Already compatible, no update needed.
-	 */
-	None,
-	/**
-	 * Schema can be upgraded leaving tree as is.
-	 */
-	SchemaCompatible,
-	/**
-	 * No update currently supported.
-	 */
-	Incompatible,
-}
-
 /**
- * Returns how compatible updating checkout's schema is with the viewSchema.
- */
-export function evaluateUpdate(
-	viewSchema: SchemaCompatibilityTester,
-	checkout: ITreeCheckout,
-): UpdateType {
-	const compatibility = viewSchema.checkCompatibility(checkout.storedSchema);
-
-	if (compatibility.canUpgrade && compatibility.canView) {
-		// Compatible as is
-		return UpdateType.None;
-	}
-
-	if (!compatibility.canUpgrade) {
-		// Existing stored schema permits trees which are incompatible with the view schema, so schema can not be updated
-		return UpdateType.Incompatible;
-	}
-
-	assert(!compatibility.canView, 0x8bd /* unexpected case */);
-	assert(compatibility.canUpgrade, 0x8be /* unexpected case */);
-
-	return UpdateType.SchemaCompatible;
-}
-
-export function canInitialize(checkout: ITreeCheckout): boolean {
-	// Check for empty.
-	return checkout.forest.isEmpty && schemaDataIsEmpty(checkout.storedSchema);
-}
-
-function normalizeNewFieldContent(
-	content: readonly ITreeCursorSynchronous[] | ITreeCursorSynchronous | undefined,
-): ITreeCursorSynchronous {
-	if (content === undefined) {
-		return cursorForMapTreeField([]);
-	}
-
-	if (isReadonlyArray(content)) {
-		return cursorForMapTreeField(content.map((c) => mapTreeFromCursor(c)));
-	}
-
-	if (content.mode === CursorLocationType.Fields) {
-		return content;
-	}
-
-	return cursorForMapTreeField([mapTreeFromCursor(content)]);
-}
-
-/**
- * Initialize a checkout with a schema and tree content.
- * This function should only be called when the tree is uninitialized (no schema or content).
- * @remarks
- *
- * If the proposed schema (from `treeContent`) is not compatible with the empty tree, this function handles using an intermediate schema
- * which supports the empty tree as well as the final tree content.
- */
-export function initialize(checkout: ITreeCheckout, treeContent: TreeStoredContent): void {
-	checkout.transaction.start();
-	try {
-		initializeContent(checkout, treeContent.schema, () => {
-			const field = { field: rootFieldKey, parent: undefined };
-			const content = normalizeNewFieldContent(treeContent.initialTree);
-			const contentChunk = checkout.forest.chunkField(content);
-
-			switch (checkout.storedSchema.rootFieldSchema.kind) {
-				case FieldKinds.optional.identifier: {
-					const fieldEditor = checkout.editor.optionalField(field);
-					assert(
-						content.getFieldLength() <= 1,
-						0x7f4 /* optional field content should normalize at most one item */,
-					);
-					fieldEditor.set(contentChunk.topLevelLength === 0 ? undefined : contentChunk, true);
-					break;
-				}
-				case FieldKinds.sequence.identifier: {
-					const fieldEditor = checkout.editor.sequenceField(field);
-					// TODO: should do an idempotent edit here.
-					fieldEditor.insert(0, contentChunk);
-					break;
-				}
-				default: {
-					fail(0xac7 /* unexpected root field kind during initialize */);
-				}
-			}
-		});
-	} finally {
-		checkout.transaction.commit();
-	}
-}
-
-/**
- * Ensure a {@link ITreeCheckout} can be used with a given {@link SchemaCompatibilityTester}.
- *
+ * Construct a general purpose `setInitialTree` for use with {@link initialize} from a function that returns a chunk.
+ * @param contentFactory - A function that returns the initial tree content as a chunk.
+ * Invoked after a schema containing all nodes from newSchema is applied.
+ * Note that the final root field schema may not have been applied yet: if the root is required, it will be optional at this time
+ * (so the root being empty before the insertion is not out of schema).
  * @remarks
- * It is up to the caller to ensure that compatibility is reevaluated if the checkout's stored schema is edited in the future.
- *
- * @param viewSchema - View schema that `checkout` should be made compatible with.
- * @param allowedSchemaModifications - Flags enum describing the ways this is allowed to modify `checkout`.
- * @param checkout - To be modified as needed to be compatible with `viewSchema`.
- * @param treeContent - Content to be used to initialize `checkout`'s the tree if needed and allowed.
- * @returns true iff checkout now is compatible with `viewSchema`.
+ * This does not support sequence roots as they are not allowed in the public API surface.
+ * A test utility for them can be found as `initializeSequenceRoot` for testing internal logic which uses a sequence root.
  */
-export function ensureSchema(
-	viewSchema: SchemaCompatibilityTester,
-	checkout: ITreeCheckout,
-): boolean {
-	const updatedNeeded = evaluateUpdate(viewSchema, checkout);
-	switch (updatedNeeded) {
-		case UpdateType.None: {
-			return true;
-		}
-		case UpdateType.Incompatible: {
-			return false;
-		}
-		case UpdateType.SchemaCompatible: {
-			checkout.updateSchema(toUpgradeSchema(viewSchema.viewSchema.root));
-			return true;
-		}
-		default: {
-			unreachableCase(updatedNeeded);
-		}
-	}
+export function initializerFromChunk(
+	checkout: Pick<ITreeCheckout, "storedSchema"> & {
+		readonly editor: IDefaultEditBuilder;
+	},
+	contentFactory: () => TreeChunk,
+): () => void {
+	return () => initializeFromChunk(checkout, contentFactory());
 }
 
-/**
- * Content that can populate a `SharedTree`.
- */
-export interface TreeStoredContent {
-	readonly schema: TreeStoredSchema;
-
-	/**
-	 * Default tree content to initialize the tree with iff the tree is uninitialized
-	 * (meaning it does not even have any schema set at all).
-	 */
-	readonly initialTree: readonly ITreeCursorSynchronous[] | ITreeCursorSynchronous | undefined;
+function initializeFromChunk(
+	checkout: Pick<ITreeCheckout, "storedSchema"> & {
+		readonly editor: IDefaultEditBuilder;
+	},
+	contentChunk: TreeChunk,
+): void {
+	const field = { field: rootFieldKey, parent: undefined };
+	assert(
+		checkout.storedSchema.rootFieldSchema.kind === FieldKinds.optional.identifier,
+		0xc11 /* initializerFromChunk only supports optional roots */,
+	);
+	const fieldEditor = checkout.editor.optionalField(field);
+	assert(
+		contentChunk.topLevelLength <= 1,
+		0x7f4 /* optional field content should normalize at most one item */,
+	);
+	fieldEditor.set(contentChunk.topLevelLength === 0 ? undefined : contentChunk, true);
 }

package/src/shared-tree/schematizingTreeView.ts

@@ -16,7 +16,7 @@ import { anchorSlot } from "../core/index.js";
 import {
 	type NodeIdentifierManager,
 	defaultSchemaPolicy,
-	cursorForMapTreeNode,
+	cursorForMapTreeField,
 	TreeStatus,
 	Context,
 } from "../feature-libraries/index.js";
@@ -55,6 +55,7 @@ import {
 	FieldSchemaAlpha,
 	TreeViewConfigurationAlpha,
 	toInitialSchema,
+	toUpgradeSchema,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -63,7 +64,7 @@ import {
 	type WithBreakable,
 } from "../util/index.js";
 
-import { canInitialize, ensureSchema, initialize } from "./schematizeTree.js";
+import { canInitialize, initialize, initializerFromChunk } from "./schematizeTree.js";
 import type { ITreeCheckout, TreeCheckout } from "./treeCheckout.js";
 
 /**
@@ -184,10 +185,19 @@ export class SchematizingSimpleTreeView<
 				schema.rootFieldSchema,
 			);
 
-			initialize(this.checkout, {
+			this.checkout.transaction.start();
+
+			initialize(
+				this.checkout,
 				schema,
-				initialTree: mapTree === undefined ? undefined : cursorForMapTreeNode(mapTree),
-			});
+				initializerFromChunk(this.checkout, () => {
+					// This must be done after initial schema is set!
+					return this.checkout.forest.chunkField(
+						cursorForMapTreeField(mapTree === undefined ? [] : [mapTree]),
+					);
+				}),
+			);
+			this.checkout.transaction.commit();
 		});
 	}
 
@@ -206,10 +216,8 @@ export class SchematizingSimpleTreeView<
 			);
 		}
 
-		this.runSchemaEdit(() => {
-			const result = ensureSchema(this.viewSchema, this.checkout);
-			assert(result, 0x8bf /* Schema upgrade should always work if canUpgrade is set. */);
-		});
+		const newSchema = toUpgradeSchema(this.viewSchema.viewSchema.root);
+		this.runSchemaEdit(() => this.checkout.updateSchema(newSchema));
 	}
 
 	/**

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

@@ -14,7 +14,8 @@ import {
 import type { GraphCommit, TaggedChange } from "../core/index.js";
 import { disposeSymbol, hasSome } from "../util/index.js";
 
-import type { ChangeEnricherReadonlyCheckout, ResubmitMachine } from "./index.js";
+import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
+import type { ResubmitMachine } from "./resubmitMachine.js";
 
 interface PendingChange<TChange> {
 	commit: GraphCommit<TChange>;

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

@@ -47,7 +47,10 @@ export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
 
 /**
  * Stores annotations for an individual allowed type.
+ * @remarks
+ * Create using APIs on {@link SchemaFactoryAlpha}, like {@link SchemaStaticsAlpha.staged}.
  * @alpha
+ * @sealed
  */
 export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
 	/**
@@ -61,19 +64,12 @@ export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
 }
 
 /**
- * Stores annotations for a set of evaluated annotated allowed types.
+ * {@link AnnotatedAllowedTypes} but with the lazy schema references eagerly evaluated.
+ * @sealed
  * @alpha
  */
-export interface NormalizedAnnotatedAllowedTypes {
-	/**
-	 * Annotations that apply to a set of allowed types.
-	 */
-	readonly metadata: AllowedTypesMetadata;
-	/**
-	 * All the evaluated allowed types that the annotations apply to. The types themselves are also individually annotated.
-	 */
-	readonly types: readonly AnnotatedAllowedType<TreeNodeSchema>[];
-}
+export interface NormalizedAnnotatedAllowedTypes
+	extends AnnotatedAllowedTypes<TreeNodeSchema> {}
 
 /**
  * Checks if the input is an {@link AnnotatedAllowedTypes}.
@@ -91,8 +87,9 @@ export function isAnnotatedAllowedTypes(
 /**
  * Stores annotations for a set of allowed types.
  * @alpha
+ * @sealed
  */
-export interface AnnotatedAllowedTypes {
+export interface AnnotatedAllowedTypes<T = LazyItem<TreeNodeSchema>> {
 	/**
 	 * Annotations that apply to a set of allowed types.
 	 */
@@ -100,7 +97,7 @@ export interface AnnotatedAllowedTypes {
 	/**
 	 * All the allowed types that the annotations apply to. The types themselves may also have individual annotations.
 	 */
-	readonly types: readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[];
+	readonly types: readonly AnnotatedAllowedType<T>[];
 }
 
 /**
@@ -108,6 +105,7 @@ export interface AnnotatedAllowedTypes {
  * @remarks
  * Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
  * @alpha
+ * @input
  */
 export interface AllowedTypesMetadata {
 	/**
@@ -132,6 +130,7 @@ export function isAnnotatedAllowedType(
  * @remarks
  * Additional optionals may be added to this as non-breaking changes, so implementations of it should be simple object literals with no unlisted members.
  * @alpha
+ * @input
  */
 export interface AllowedTypeMetadata {
 	/**
@@ -208,6 +207,7 @@ export type ImplicitAllowedTypes = AllowedTypes | TreeNodeSchema;
  * Types of {@link TreeNode|TreeNodes} or {@link TreeLeafValue|TreeLeafValues} allowed at a location in a tree with
  * additional metadata associated with the location they're allowed at.
  * @alpha
+ * @input
  */
 export type ImplicitAnnotatedAllowedTypes =
 	| TreeNodeSchema
@@ -226,9 +226,18 @@ export type UnannotateImplicitAllowedTypes<T extends ImplicitAnnotatedAllowedTyp
 			? UnannotateAllowedTypesList<[T]>
 			: T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]
 				? UnannotateAllowedTypesList<T>
-				: T extends TreeNodeSchema
+				: // This should able to just return `T` here, however doing so breaks generic code in ArrayNode.
+					T extends TreeNodeSchema
 					? T
-					: never;
+					: // Ideally this case would not be hit as it should be impossible.
+						// Due to limitations of TypeScript some generic code does depend on this case,
+						// so return a valid nonspecific schema in this otherwise unreachable case.
+						// This ensures that when this case is hit, the type system can still reason about it.
+						// It also ensures that if bugs cause this to matter in other cases, they will err on the side of restricting the API
+						// (due to non-specific schema) rather than being unsafe.
+						// This helps any such bugs be noticed more easily, be less likely to lead to runtime errors,
+						// and be more likely to be fixable as non-breaking changes.
+						ImplicitAllowedTypes;
 
 /**
  * Removes annotations from a list of allowed types that may contain annotations.
@@ -395,7 +404,7 @@ export function evaluateLazySchema<T extends TreeNodeSchema>(value: LazyItem<T>)
  * Throws a UsageError if the provided schema is undefined, most likely due to being used before it was initialized.
  */
 export function checkForUninitializedSchema(
-	schema: ImplicitAnnotatedAllowedTypes | LazyItem<TreeNodeSchema>,
+	schema: ImplicitAnnotatedAllowedTypes | LazyItem<TreeNodeSchema> | AnnotatedAllowedType,
 ): void {
 	if (schema === undefined) {
 		throw new UsageError(

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

@@ -10,6 +10,7 @@ import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
 import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
 // eslint-disable-next-line import/no-deprecated
 import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
+import { markEager } from "./flexList.js";
 
 /**
  * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
@@ -37,13 +38,10 @@ import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType
  * @privateRemarks
  * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
  * and some runtime enforcement of schema class policy (see the the validation in the constructor).
- * This class is however only `type` exported not value exported, preventing the class object from being used,
- * similar to how interfaces work.
  *
  * Not all node implementations include this in their prototype chain (some hide it with a proxy),
  * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.
  * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.
- * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).
  * @sealed @public
  */
 export abstract class TreeNode implements WithType {
@@ -138,6 +136,8 @@ export abstract class TreeNode implements WithType {
 		}
 	}
 }
+// Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.
+markEager(TreeNode);
 
 /**
  * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.

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

@@ -8,7 +8,6 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { type FlexTreeNode, isFlexTreeNode } from "../../feature-libraries/index.js";
 
-import { markEager } from "./flexList.js";
 import { inPrototypeChain, privateToken, TreeNode } from "./treeNode.js";
 import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
 import {
@@ -209,8 +208,6 @@ export abstract class TreeNodeValid<TInput> extends TreeNode {
 		return result;
 	}
 }
-// Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.
-markEager(TreeNodeValid);
 
 /**
  * Data cached about the most derived type in a schema's class hierarchy.

package/src/simple-tree/fieldSchema.ts

@@ -620,8 +620,9 @@ function arePersistedMetadataEqual(
 export type ImplicitFieldSchema = FieldSchema | ImplicitAllowedTypes;
 
 /**
- * Annotated schema for a field of a tree node.
+ * {@link ImplicitFieldSchema} which supports {@link AnnotatedAllowedTypes | annotations} on the allowed types.
  * @alpha
+ * @input
  */
 export type ImplicitAnnotatedFieldSchema = FieldSchema | ImplicitAnnotatedAllowedTypes;
 

package/src/simple-tree/index.ts

@@ -14,9 +14,7 @@ export {
 	type TreeNodeSchemaClass,
 	type TreeNodeSchemaNonClass,
 	type TreeNodeSchemaCore,
-	// TreeNode is only type exported, which prevents use of the class object for unsupported use-cases like direct sub-classing and instanceof.
-	// See docs on TreeNode for more details.
-	type TreeNode,
+	TreeNode,
 	type Unhydrated,
 	type InternalTreeNode,
 	isTreeNode,