@fluidframework/tree 2.41.0-338401 → 2.42.0

package/src/core/tree/pathTree.ts

@@ -177,7 +177,8 @@ export type NodeIndex = number;
 export type PlaceIndex = number;
 
 /**
- * @returns the number of nodes above this one.
+ * Gets the number of nodes above this one.
+ * @remarks
  * Zero when the path's parent is undefined, meaning the path represents a node in a detached field.
  * Runs in O(depth) time.
  */
@@ -192,14 +193,14 @@ export function getDepth(path: UpPath): number {
 }
 
 /**
- * @returns a deep copy of the provided path as simple javascript objects.
- * This is safe to hold onto and use deep object comparisons on.
+ * Creates deep copy of the provided path as simple JavaScript object.
+ * @remarks This is safe to hold onto and use deep object comparisons on.
  */
 export function clonePath(path: UpPath): UpPath;
 
 /**
- * @returns a deep copy of the provided path as simple javascript objects.
- * This is safe to hold onto and use deep object comparisons on.
+ * Creates a deep copy of the provided path as simple JavaScript object.
+ * @remarks This is safe to hold onto and use deep object comparisons on.
  */
 export function clonePath(path: UpPath | undefined): UpPath | undefined;
 
@@ -215,8 +216,8 @@ export function clonePath(path: UpPath | undefined): UpPath | undefined {
 }
 
 /**
- * @returns The elements of the given `path`, ordered from root-most to child-most.
- * These elements are unchanged and therefore still point "up".
+ * Gets the elements of the given `path`, ordered from root-most to child-most.
+ * @remarks These elements are unchanged and therefore still point "up".
  */
 export function topDownPath(path: UpPath | undefined): UpPath[] {
 	const out: UpPath[] = [];
@@ -230,8 +231,8 @@ export function topDownPath(path: UpPath | undefined): UpPath[] {
 }
 
 /**
- * @returns true iff `a` and `b` describe the same path.
- *
+ * Returns true if and only if `a` and `b` describe the same path.
+ * @remarks
  * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.
  */
 export function compareUpPaths(a: UpPath | undefined, b: UpPath | undefined): boolean {
@@ -249,8 +250,8 @@ export function compareUpPaths(a: UpPath | undefined, b: UpPath | undefined): bo
 }
 
 /**
- * @returns true iff `a` and `b` describe the same field path.
- *
+ * Returns true if and only if `a` and `b` describe the same field path.
+ * @remarks
  * Note that for mutable paths (as used in `AnchorSet`), this equality may change over time: this only checks if the two paths are currently the same.
  */
 export function compareFieldUpPaths(a: FieldUpPath, b: FieldUpPath): boolean {

package/src/core/tree/treeTextFormat.ts

@@ -140,7 +140,7 @@ export function setGenericTreeField<T>(
 }
 
 /**
- * @returns keys for fields of `tree`.
+ * Returns keys for fields of `tree`.
  */
 export function genericTreeKeys<T>(tree: GenericFieldsNode<T>): readonly FieldKey[] {
 	const fields = tree.fields;

package/src/core/tree/visitorUtils.ts

@@ -5,7 +5,7 @@
 
 import type { IIdCompressor } from "@fluidframework/id-compressor";
 
-import type { ICodecOptions } from "../../codec/index.js";
+import type { CodecWriteOptions } from "../../codec/index.js";
 import { type IdAllocator, idAllocatorFromMaxId } from "../../util/index.js";
 import type { RevisionTag, RevisionTagCodec } from "../rebase/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
@@ -21,7 +21,7 @@ export function makeDetachedFieldIndex(
 	prefix: string = "Temp",
 	revisionTagCodec: RevisionTagCodec,
 	idCompressor: IIdCompressor,
-	options?: ICodecOptions,
+	options?: CodecWriteOptions,
 ): DetachedFieldIndex {
 	return new DetachedFieldIndex(
 		prefix,

package/src/feature-libraries/chunked-forest/chunkedForest.ts

@@ -468,7 +468,7 @@ class Cursor extends BasicChunkCursor implements ITreeSubscriptionCursor {
 }
 
 /**
- * @returns an implementation of {@link IEditableForest} with no data or schema.
+ * Creates an implementation of {@link IEditableForest} with no data or schema.
  */
 export function buildChunkedForest(
 	chunker: IChunker,

package/src/feature-libraries/default-schema/defaultEditBuilder.ts

@@ -434,8 +434,9 @@ export interface OptionalFieldEditBuilder<TContent> {
 }
 
 /**
+ * Edit builder for the sequence field kind.
  */
-export interface SequenceFieldEditBuilder<TContent> {
+export interface SequenceFieldEditBuilder<TContent, TRemoved = void> {
 	/**
 	 * Issues a change which inserts the `newContent` at the given `index`.
 	 * @param index - the index at which to insert the `newContent`.
@@ -448,11 +449,11 @@ export interface SequenceFieldEditBuilder<TContent> {
 	 * @param index - The index of the first removed element.
 	 * @param count - The number of elements to remove.
 	 */
-	remove(index: number, count: number): void;
+	remove(index: number, count: number): TRemoved;
 }
 
 /**
- * @returns The number of path elements that both paths share, starting at index 0.
+ * Gets the number of path elements that both paths share, starting at index 0.
  */
 function getSharedPrefixLength(pathA: readonly UpPath[], pathB: readonly UpPath[]): number {
 	const minDepth = Math.min(pathA.length, pathB.length);

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

@@ -27,7 +27,7 @@ export {
 } from "./defaultEditBuilder.js";
 
 export {
-	SchemaValidationErrors,
+	SchemaValidationError,
 	isNodeInSchema,
 	isFieldInSchema,
 	inSchemaOrThrow,

package/src/feature-libraries/default-schema/schemaChecker.ts

@@ -4,9 +4,9 @@
  */
 
 import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
-	type MapTree,
 	type TreeFieldStoredSchema,
 	LeafNodeStoredSchema,
 	ObjectNodeStoredSchema,
@@ -15,27 +15,30 @@ import {
 	type SchemaAndPolicy,
 } from "../../core/index.js";
 import { allowsValue } from "../valueUtilities.js";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import type { MapTreeFieldViewGeneric, MinimalMapTreeNodeView } from "../mapTreeCursor.js";
+import { iterableHasSome, mapIterable } from "../../util/index.js";
 
-export const enum SchemaValidationErrors {
-	NoError,
+export enum SchemaValidationError {
 	Field_KindNotInSchemaPolicy,
-	Field_IncorrectMultiplicity,
+	Field_MissingRequiredChild,
+	Field_MultipleChildrenNotAllowed,
+	Field_ChildInForbiddenField,
 	Field_NodeTypeNotAllowed,
 	LeafNode_InvalidValue,
 	LeafNode_FieldsNotAllowed,
 	ObjectNode_FieldNotInSchema,
 	NonLeafNode_ValueNotAllowed,
 	Node_MissingSchema,
-	UnknownError,
 }
 
 /**
  * Throws a UsageError if maybeError indicates a tree is out of schema.
  */
-export function inSchemaOrThrow(maybeError: SchemaValidationErrors): void {
-	if (maybeError !== SchemaValidationErrors.NoError) {
-		throw new UsageError("Tree does not conform to schema.");
+export function inSchemaOrThrow(maybeError: SchemaValidationError | undefined): void {
+	if (maybeError !== undefined) {
+		throw new UsageError(
+			`Tree does not conform to schema: ${SchemaValidationError[maybeError]}`,
+		);
 	}
 }
 
@@ -43,35 +46,35 @@ export function inSchemaOrThrow(maybeError: SchemaValidationErrors): void {
  * Deeply checks that the provided node complies with the schema based on its identifier.
  */
 export function isNodeInSchema(
-	node: MapTree,
+	node: MinimalMapTreeNodeView,
 	schemaAndPolicy: SchemaAndPolicy,
-): SchemaValidationErrors {
+): SchemaValidationError | undefined {
 	// Validate the schema declared by the node exists
 	const schema = schemaAndPolicy.schema.nodeSchema.get(node.type);
 	if (schema === undefined) {
-		return SchemaValidationErrors.Node_MissingSchema;
+		return SchemaValidationError.Node_MissingSchema;
 	}
 
 	// Validate the node is well formed according to its schema
 
 	if (schema instanceof LeafNodeStoredSchema) {
-		if (node.fields.size !== 0) {
-			return SchemaValidationErrors.LeafNode_FieldsNotAllowed;
+		if (iterableHasSome(node.fields)) {
+			return SchemaValidationError.LeafNode_FieldsNotAllowed;
 		}
 		if (!allowsValue(schema.leafValue, node.value)) {
-			return SchemaValidationErrors.LeafNode_InvalidValue;
+			return SchemaValidationError.LeafNode_InvalidValue;
 		}
 	} else {
 		if (node.value !== undefined) {
-			return SchemaValidationErrors.NonLeafNode_ValueNotAllowed;
+			return SchemaValidationError.NonLeafNode_ValueNotAllowed;
 		}
 
 		if (schema instanceof ObjectNodeStoredSchema) {
-			const uncheckedFieldsFromNode = new Set(node.fields.keys());
+			const uncheckedFieldsFromNode = new Set(mapIterable(node.fields, ([key, field]) => key));
 			for (const [fieldKey, fieldSchema] of schema.objectNodeFields) {
 				const nodeField = node.fields.get(fieldKey) ?? [];
 				const fieldInSchemaResult = isFieldInSchema(nodeField, fieldSchema, schemaAndPolicy);
-				if (fieldInSchemaResult !== SchemaValidationErrors.NoError) {
+				if (fieldInSchemaResult !== undefined) {
 					return fieldInSchemaResult;
 				}
 				uncheckedFieldsFromNode.delete(fieldKey);
@@ -81,12 +84,12 @@ export function isNodeInSchema(
 				uncheckedFieldsFromNode.size !== 0 &&
 				!schemaAndPolicy.policy.allowUnknownOptionalFields(node.type)
 			) {
-				return SchemaValidationErrors.ObjectNode_FieldNotInSchema;
+				return SchemaValidationError.ObjectNode_FieldNotInSchema;
 			}
 		} else if (schema instanceof MapNodeStoredSchema) {
-			for (const field of node.fields.values()) {
+			for (const [_key, field] of node.fields) {
 				const fieldInSchemaResult = isFieldInSchema(field, schema.mapFields, schemaAndPolicy);
-				if (fieldInSchemaResult !== SchemaValidationErrors.NoError) {
+				if (fieldInSchemaResult !== undefined) {
 					return fieldInSchemaResult;
 				}
 			}
@@ -95,42 +98,45 @@ export function isNodeInSchema(
 		}
 	}
 
-	return SchemaValidationErrors.NoError;
+	return undefined;
 }
 
 /**
  * Deeply checks that the nodes comply with the field schema and included schema.
  */
 export function isFieldInSchema(
-	childNodes: readonly MapTree[],
+	childNodes: MapTreeFieldViewGeneric<MinimalMapTreeNodeView>,
 	schema: TreeFieldStoredSchema,
 	schemaAndPolicy: SchemaAndPolicy,
-): SchemaValidationErrors {
+): SchemaValidationError | undefined {
 	// Validate that the field kind is handled by the schema policy
 	const kind = schemaAndPolicy.policy.fieldKinds.get(schema.kind);
 	if (kind === undefined) {
-		return SchemaValidationErrors.Field_KindNotInSchemaPolicy;
+		return SchemaValidationError.Field_KindNotInSchemaPolicy;
 	}
 
 	// Validate that the field doesn't contain more nodes than its type supports
-	if (!compliesWithMultiplicity(childNodes.length, kind.multiplicity)) {
-		return SchemaValidationErrors.Field_IncorrectMultiplicity;
+	{
+		const multiplicityCheck = compliesWithMultiplicity(childNodes.length, kind.multiplicity);
+		if (multiplicityCheck !== undefined) {
+			return multiplicityCheck;
+		}
 	}
 
 	for (const node of childNodes) {
 		// Validate the type declared by the node is allowed in this field
 		if (schema.types !== undefined && !schema.types.has(node.type)) {
-			return SchemaValidationErrors.Field_NodeTypeNotAllowed;
+			return SchemaValidationError.Field_NodeTypeNotAllowed;
 		}
 
 		// Validate the node complies with the type it declares to be.
 		const nodeInSchemaResult = isNodeInSchema(node, schemaAndPolicy);
-		if (nodeInSchemaResult !== SchemaValidationErrors.NoError) {
+		if (nodeInSchemaResult !== undefined) {
 			return nodeInSchemaResult;
 		}
 	}
 
-	return SchemaValidationErrors.NoError;
+	return undefined;
 }
 
 /**
@@ -142,16 +148,26 @@ export function isFieldInSchema(
 export function compliesWithMultiplicity(
 	numberOfItems: number,
 	multiplicity: Multiplicity,
-): boolean {
+): SchemaValidationError | undefined {
 	switch (multiplicity) {
 		case Multiplicity.Single:
-			return numberOfItems === 1;
+			if (numberOfItems < 1) {
+				return SchemaValidationError.Field_MissingRequiredChild;
+			} else if (numberOfItems > 1) {
+				return SchemaValidationError.Field_MultipleChildrenNotAllowed;
+			} else {
+				return undefined;
+			}
 		case Multiplicity.Optional:
-			return numberOfItems <= 1;
+			return numberOfItems > 1
+				? SchemaValidationError.Field_MultipleChildrenNotAllowed
+				: undefined;
 		case Multiplicity.Sequence:
-			return true;
+			return undefined;
 		case Multiplicity.Forbidden:
-			return numberOfItems === 0;
+			return numberOfItems === 0
+				? undefined
+				: SchemaValidationError.Field_ChildInForbiddenField;
 		default:
 			unreachableCase(multiplicity);
 	}

package/src/feature-libraries/flex-tree/context.ts

@@ -3,23 +3,26 @@
  * Licensed under the MIT License.
  */
 
+import type { Listenable } from "@fluidframework/core-interfaces";
 import { assert, debugAssert } from "@fluidframework/core-utils/internal";
 
 import {
+	type DetachedField,
+	type FieldKindIdentifier,
 	type ForestEvents,
 	type SchemaPolicy,
 	type TreeStoredSchema,
 	anchorSlot,
 	moveToDetachedField,
+	rootField,
 } from "../../core/index.js";
-import type { Listenable } from "@fluidframework/core-interfaces";
+import type { ITreeCheckout } from "../../shared-tree/index.js";
 import { type IDisposable, disposeSymbol } from "../../util/index.js";
 import type { NodeIdentifierManager } from "../node-identifier/index.js";
 
 import type { FlexTreeField } from "./flexTreeTypes.js";
 import type { LazyEntity } from "./lazyEntity.js";
 import { makeField } from "./lazyField.js";
-import type { ITreeCheckout } from "../../shared-tree/index.js";
 
 /**
  * Context for FlexTrees.
@@ -51,16 +54,12 @@ export interface FlexTreeContext {
 }
 
 /**
- * A common context of a "forest" of FlexTrees.
- * It handles group operations like transforming cursors into anchors for edits.
+ * Subset of a hydrated context which can be used in more cases (like before the root and events are set up).
  */
-export interface FlexTreeHydratedContext extends FlexTreeContext {
-	readonly events: Listenable<ForestEvents>;
+export interface FlexTreeHydratedContextMinimal {
 	/**
-	 * Gets the root field of the tree.
+	 * The {@link NodeIdentifierManager} responsible for allocating and compressing identifiers for nodes in this context.
 	 */
-	get root(): FlexTreeField;
-
 	readonly nodeKeyManager: NodeIdentifierManager;
 
 	/**
@@ -69,6 +68,20 @@ export interface FlexTreeHydratedContext extends FlexTreeContext {
 	readonly checkout: ITreeCheckout;
 }
 
+/**
+ * A common context of a "forest" of FlexTrees.
+ * It handles group operations like transforming cursors into anchors for edits.
+ */
+export interface FlexTreeHydratedContext
+	extends FlexTreeContext,
+		FlexTreeHydratedContextMinimal {
+	readonly events: Listenable<ForestEvents>;
+	/**
+	 * Gets the root field of the tree.
+	 */
+	get root(): FlexTreeField;
+}
+
 /**
  * Creating multiple flex tree contexts for the same branch, and thus with the same underlying AnchorSet does not work due to how TreeNode caching works.
  * This slot is used to detect if one already exists and error if creating a second.
@@ -82,6 +95,8 @@ export const ContextSlot = anchorSlot<Context>();
  *
  * A {@link FlexTreeContext} which is used to manage the cursors and anchors within the FlexTrees:
  * This is necessary for supporting using this tree across edits to the forest, and not leaking memory.
+ *
+ * This context and the trees it produces observe the kinds of fields from the schema
  */
 export class Context implements FlexTreeHydratedContext, IDisposable {
 	public readonly withCursors: Set<LazyEntity> = new Set();
@@ -159,6 +174,7 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 
 	/**
 	 * Release any cursors and anchors held by tree entities created in this context.
+	 * @remarks
 	 * Ensures the cashed references to those entities on the Anchors are also cleared.
 	 * The tree entities are invalid to use after this, but the context may still be used
 	 * to create new trees starting from the root.
@@ -172,17 +188,32 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 		assert(this.withAnchors.size === 0, 0x775 /* free should remove all anchors */);
 	}
 
+	/**
+	 * Gets the root field of the tree.
+	 * @remarks
+	 * This is a cached value: it should not be disposed by the accessor.
+	 * Like all other fields from this context, it will become invalid to use after {@link clear} is called or the {@link disposeSymbol} method is called.
+	 */
 	public get root(): FlexTreeField {
 		assert(this.disposed === false, 0x804 /* use after dispose */);
-		if (this.lazyRootCache !== undefined) {
-			return this.lazyRootCache;
-		}
+
+		this.lazyRootCache ??= this.detachedField(rootField, this.schema.rootFieldSchema.kind);
+		return this.lazyRootCache;
+	}
+
+	/**
+	 * Returns a new {@link FlexTreeField} that will live as long as the caller allows up to the next call to {@link clear} or disposal of the context.
+	 * @remarks
+	 * Due to limited support for detached fields, not all operations are supported.
+	 * Additionally if the detached field's content is deleted, the field will become out of schema if it is required: it must not be used after that point.
+	 */
+	public detachedField(key: DetachedField, schema: FieldKindIdentifier): FlexTreeField {
+		assert(this.disposed === false, 0xb9c /* use after dispose */);
 
 		const cursor = this.checkout.forest.allocateCursor("root");
-		moveToDetachedField(this.checkout.forest, cursor);
-		const field = makeField(this, this.schema.rootFieldSchema.kind, cursor);
+		moveToDetachedField(this.checkout.forest, cursor, key);
+		const field = makeField(this, schema, cursor);
 		cursor.free();
-		this.lazyRootCache = field;
 		return field;
 	}
 

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -5,7 +5,6 @@
 
 import {
 	type AnchorNode,
-	type ExclusiveMapTree,
 	type FieldKey,
 	type FieldKindIdentifier,
 	type ITreeCursorSynchronous,
@@ -20,15 +19,16 @@ import type {
 	ValueFieldEditBuilder,
 	OptionalFieldEditBuilder,
 } from "../default-schema/index.js";
+import type { MinimalMapTreeNodeView } from "../mapTreeCursor.js";
 import type { FlexFieldKind } from "../modular-schema/index.js";
 
-import type { FlexTreeContext } from "./context.js";
+import type { FlexTreeContext, FlexTreeHydratedContext } from "./context.js";
 
 /**
  * An anchor slot which records the {@link FlexTreeNode} associated with that anchor, if there is one.
  * @remarks This always points to a "real" {@link FlexTreeNode} (i.e. a `LazyTreeNode`), never to a "raw" node.
  */
-export const flexTreeSlot = anchorSlot<FlexTreeNode>();
+export const flexTreeSlot = anchorSlot<HydratedFlexTreeNode>();
 
 /**
  * Indicates that an object is a flex tree.
@@ -98,6 +98,10 @@ export enum TreeStatus {
 	 * Nodes can enter this state for multiple reasons:
 	 * - The node was removed and nothing (e.g. undo/redo history) kept it from being cleaned up.
 	 * - The {@link TreeView} was disposed or had a schema change which made the tree incompatible.
+	 *
+	 * Deleted nodes' contents should not be observed or edited. This includes functionality exposed via {@link (Tree:variable)},
+	 * with the exception of {@link TreeNodeApi.status}.
+	 *
 	 * @privateRemarks
 	 * There was planned work (AB#17948) to make the first reason a node could become "Deleted" impossible,
 	 * at least as an opt in feature,
@@ -119,8 +123,9 @@ export enum TreeStatus {
 	 *
 	 * - Transactions do not work: transactions apply to a single {@link TreeView}, and `New` nodes are not part of one.
 	 *
-	 * - `Tree.shortId` (when the identifier was explicitly specified and thus works at all) will just return the full identifier as a string,
-	 * but might return a compressed form as a number once hydrated.
+	 * - Automatically generated {@link SchemaFactory.identifier | identifiers} will be less compressible if read.
+	 *
+	 * - {@link TreeIdentifierUtils.getShort} and {@link TreeNodeApi.shortId | Tree.shortId} cannot return their short identifiers.
 	 */
 	New = 3,
 }
@@ -168,16 +173,6 @@ export interface FlexTreeNode extends FlexTreeEntity {
 
 	boxedIterator(): IterableIterator<FlexTreeField>;
 
-	/**
-	 * The anchor node associated with this node
-	 *
-	 * @remarks
-	 * The ref count keeping this alive is owned by the FlexTreeNode:
-	 * if holding onto this anchor for longer than the FlexTreeNode might be alive,
-	 * a separate Anchor (and thus ref count) must be allocated to keep it alive.
-	 */
-	readonly anchorNode: AnchorNode;
-
 	/**
 	 * Returns an iterable of keys for non-empty fields.
 	 *
@@ -201,6 +196,33 @@ export interface FlexTreeNode extends FlexTreeEntity {
 	 * Must not be held onto across edits or any other tree API use.
 	 */
 	borrowCursor(): ITreeCursorSynchronous;
+
+	/**
+	 * If true, this node is a {@link HydratedFlexTreeNode}.
+	 *
+	 * If false, this node is unhydrated.
+	 */
+	isHydrated(): this is HydratedFlexTreeNode;
+}
+
+/**
+ * A FlexTreeNode that is hydrated, meaning it is associated with a {@link FlexTreeHydratedContext}.
+ */
+export interface HydratedFlexTreeNode extends FlexTreeNode {
+	/**
+	 * {@inheritDoc FlexTreeNode.context}
+	 */
+	readonly context: FlexTreeHydratedContext;
+
+	/**
+	 * The anchor node associated with this node
+	 *
+	 * @remarks
+	 * The ref count keeping this alive is owned by the FlexTreeNode:
+	 * if holding onto this anchor for longer than the FlexTreeNode might be alive,
+	 * a separate Anchor (and thus ref count) must be allocated to keep it alive.
+	 */
+	readonly anchorNode: AnchorNode;
 }
 
 /**
@@ -277,12 +299,12 @@ export interface FlexTreeField extends FlexTreeEntity {
 /**
  * Typed tree for inserting as the content of a field.
  */
-export type FlexibleFieldContent = ExclusiveMapTree[];
+export type FlexibleFieldContent = readonly FlexibleNodeContent[];
 
 /**
  * Tree for inserting as a node.
  */
-export type FlexibleNodeContent = ExclusiveMapTree;
+export type FlexibleNodeContent = MinimalMapTreeNodeView;
 
 /**
  * {@link FlexTreeField} that stores a sequence of children.

package/src/feature-libraries/flex-tree/index.ts

@@ -17,6 +17,9 @@ export {
 	FlexTreeEntityKind,
 	isFlexTreeNode,
 	flexTreeSlot,
+	type FlexibleNodeContent,
+	type FlexibleFieldContent,
+	type HydratedFlexTreeNode,
 } from "./flexTreeTypes.js";
 
 export {
@@ -32,6 +35,7 @@ export {
 	type FlexTreeHydratedContext,
 	Context,
 	ContextSlot,
+	type FlexTreeHydratedContextMinimal,
 } from "./context.js";
 
 export { type FlexTreeNodeEvents } from "./treeEvents.js";

package/src/feature-libraries/flex-tree/lazyField.ts

@@ -30,18 +30,21 @@ import {
 	type SequenceFieldEditBuilder,
 	type ValueFieldEditBuilder,
 } from "../default-schema/index.js";
+import { cursorForMapTreeField } from "../mapTreeCursor.js";
 import type { FlexFieldKind } from "../modular-schema/index.js";
 
 import type { Context } from "./context.js";
 import {
 	FlexTreeEntityKind,
 	type FlexTreeField,
-	type FlexTreeNode,
 	type FlexTreeOptionalField,
 	type FlexTreeRequiredField,
 	type FlexTreeSequenceField,
 	type FlexTreeTypedField,
 	type FlexTreeUnknownUnboxed,
+	type FlexibleFieldContent,
+	type FlexibleNodeContent,
+	type HydratedFlexTreeNode,
 	TreeStatus,
 	flexTreeMarker,
 	flexTreeSlot,
@@ -49,7 +52,6 @@ import {
 import { LazyEntity } from "./lazyEntity.js";
 import { type LazyTreeNode, makeTree } from "./lazyNode.js";
 import { indexForAt, treeStatusFromAnchorCache } from "./utilities.js";
-import { cursorForMapTreeField } from "../mapTreeCursor.js";
 
 /**
  * Reuse fields.
@@ -159,7 +161,7 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 		return this.schema === kind.identifier;
 	}
 
-	public get parent(): FlexTreeNode | undefined {
+	public get parent(): HydratedFlexTreeNode | undefined {
 		if (this.anchor.parent === undefined) {
 			return undefined;
 		}
@@ -193,7 +195,7 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 		);
 	}
 
-	public boxedAt(index: number): FlexTreeNode | undefined {
+	public boxedAt(index: number): HydratedFlexTreeNode | undefined {
 		const finalIndex = indexForAt(index, this.length);
 
 		if (finalIndex === undefined) {
@@ -207,7 +209,7 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 		return Array.from(this, callbackfn);
 	}
 
-	public boxedIterator(): IterableIterator<FlexTreeNode> {
+	public boxedIterator(): IterableIterator<HydratedFlexTreeNode> {
 		return iterateCursorField(this.cursor, (cursor) => makeTree(this.context, cursor));
 	}
 
@@ -263,7 +265,7 @@ export class LazySequence extends LazyField implements FlexTreeSequenceField {
 		return this.map((x) => x);
 	}
 
-	public editor: SequenceFieldEditBuilder<ExclusiveMapTree[]> = {
+	public editor: SequenceFieldEditBuilder<FlexibleFieldContent> = {
 		insert: (index, newContent) => {
 			this.sequenceEditor().insert(index, cursorForMapTreeField(newContent));
 		},
@@ -279,7 +281,7 @@ export class LazySequence extends LazyField implements FlexTreeSequenceField {
 }
 
 export class LazyValueField extends LazyField implements FlexTreeRequiredField {
-	public editor: ValueFieldEditBuilder<ExclusiveMapTree> = {
+	public editor: ValueFieldEditBuilder<FlexibleNodeContent> = {
 		set: (newContent) => {
 			this.valueFieldEditor().set(cursorForMapTreeField([newContent]));
 		},