@fluidframework/tree 2.101.1 → 2.102.0

package/src/feature-libraries/chunked-forest/codec/format/versions.ts

@@ -10,6 +10,7 @@ import { strictEnum, type Values } from "../../../../util/index.js";
 import { EncodedFieldBatchGeneric } from "./formatGeneric.js";
 import { EncodedChunkShapeV1 } from "./formatV1.js";
 import { EncodedChunkShapeV2 } from "./formatV2.js";
+import { EncodedChunkShapeVTextExperimental } from "./formatVText.js";
 
 /**
  * The format version for the field batch.
@@ -29,6 +30,10 @@ export const FieldBatchFormatVersion = strictEnum("FieldBatchFormatVersion", {
 	 * {@link EncodedIncrementalChunkShape} was added in this version.
 	 */
 	v2: 2,
+	/**
+	 * Experimental codec with optimizations for text.
+	 */
+	vTextExperimental: "text",
 });
 
 /**
@@ -68,6 +73,17 @@ export const EncodedFieldBatchV2 = EncodedFieldBatchGeneric(
 	EncodedChunkShapeV2,
 );
 
+/**
+ * Encoded {@link FieldBatch} using the experimental text optimized format.
+ */
+export type EncodedFieldBatchVTextExperimental = Static<
+	typeof EncodedFieldBatchVTextExperimental
+>;
+export const EncodedFieldBatchVTextExperimental = EncodedFieldBatchGeneric(
+	FieldBatchFormatVersion.vTextExperimental,
+	EncodedChunkShapeVTextExperimental,
+);
+
 /**
  * Encoded {@link FieldBatch}, which might use V2 features, but might also have been from a V1 encoder.
  * @remarks
@@ -88,9 +104,14 @@ export type EncodedFieldBatchV1OrV2 = EncodedFieldBatchV1 | EncodedFieldBatchV2;
 export type EncodedFieldBatchV1AndV2 = EncodedFieldBatchV1 & EncodedFieldBatchV2;
 
 /**
- * Encoded chunk shape, which might use V2 features, but might also have been from a V1 encoder.
+ * An encoded chunk shape from any known {@link FieldBatchFormatVersion}.
+ *
  * @remarks
- * Type wise, equivalent to V2, as that is a superset of V1.
- * Used instead of just V2 for clarity.
+ * Use this when working with chunk shapes uniformly across versions — for example, in the
+ * shared decoder dispatcher and in encoder shape base classes. New format versions should
+ * add their chunk shape variant to this union.
  */
-export type EncodedChunkShapeV1OrV2 = EncodedChunkShapeV1 | EncodedChunkShapeV2;
+export type EncodedChunkShape =
+	| EncodedChunkShapeV1
+	| EncodedChunkShapeV2
+	| EncodedChunkShapeVTextExperimental;

package/src/feature-libraries/chunked-forest/codec/nodeEncoder.ts

@@ -4,7 +4,7 @@
  */
 
 import { assert, fail } from "@fluidframework/core-utils/internal";
-import { isStableId } from "@fluidframework/id-compressor/internal";
+import { isFinalId, isStableId } from "@fluidframework/id-compressor/internal";
 
 import {
 	type FieldKey,
@@ -25,7 +25,7 @@ import {
 	encodeValue,
 } from "./compressedEncode.js";
 import type {
-	EncodedChunkShapeV1OrV2,
+	EncodedChunkShape,
 	EncodedFieldShape,
 	EncodedValueShape,
 } from "./format/index.js";
@@ -36,10 +36,7 @@ import type {
  * The fact this is also a Shape is an implementation detail of the encoder: that allows the shape it uses to be itself,
  * which is an easy way to keep all the related code together without extra objects.
  */
-export class NodeShapeBasedEncoder
-	extends Shape<EncodedChunkShapeV1OrV2>
-	implements NodeEncoder
-{
+export class NodeShapeBasedEncoder extends Shape<EncodedChunkShape> implements NodeEncoder {
 	/**
 	 * Set of keys for fields that are encoded using {@link NodeShapeBasedEncoder.specializedFieldEncoders}.
 	 * TODO: Ensure uniform chunks, encoding and identifier generation sort fields the same.
@@ -82,8 +79,7 @@ export class NodeShapeBasedEncoder
 					// This is not the case for forest summaries at the time of writing, so non-finalized ids are instead written using
 					// their long form (by falling through to the original cursor value).
 					// A scenario where such ids can appear in the summary is in the attach summary of a tree being attached to an already-attached container.
-					// TODO: isFinalId should probably be exported from id-compressor and that could be used to do the narrowing here.
-					if (!context.isSummary || opSpaceId >= 0) {
+					if (!context.isSummary || isFinalId(opSpaceId)) {
 						return opSpaceId;
 					}
 				}
@@ -95,7 +91,7 @@ export class NodeShapeBasedEncoder
 	public encodeNode(
 		cursor: ITreeCursorSynchronous,
 		context: EncoderContext,
-		outputBuffer: BufferFormat<EncodedChunkShapeV1OrV2>,
+		outputBuffer: BufferFormat<EncodedChunkShape>,
 	): void {
 		if (this.type === undefined) {
 			outputBuffer.push(new IdentifierToken(cursor.type));
@@ -109,7 +105,7 @@ export class NodeShapeBasedEncoder
 			cursor.exitField();
 		}
 
-		const otherFieldsBuffer: BufferFormat<EncodedChunkShapeV1OrV2> = [];
+		const otherFieldsBuffer: BufferFormat<EncodedChunkShape> = [];
 
 		forEachField(cursor, () => {
 			const key = cursor.getFieldKey();
@@ -130,8 +126,8 @@ export class NodeShapeBasedEncoder
 
 	public encodeShape(
 		identifiers: DeduplicationTable<string>,
-		shapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,
-	): EncodedChunkShapeV1OrV2 {
+		shapes: DeduplicationTable<Shape<EncodedChunkShape>>,
+	): EncodedChunkShape {
 		return {
 			c: {
 				type: encodeOptionalIdentifier(this.type, identifiers),
@@ -144,7 +140,7 @@ export class NodeShapeBasedEncoder
 
 	public countReferencedShapesAndIdentifiers(
 		identifiers: Counter<string>,
-		shapeDiscovered: (shape: Shape<EncodedChunkShapeV1OrV2>) => void,
+		shapeDiscovered: (shape: Shape<EncodedChunkShape>) => void,
 	): void {
 		if (this.type !== undefined) {
 			identifiers.add(this.type);
@@ -160,7 +156,7 @@ export class NodeShapeBasedEncoder
 		}
 	}
 
-	public get shape(): Shape<EncodedChunkShapeV1OrV2> {
+	public get shape(): Shape<EncodedChunkShape> {
 		return this;
 	}
 }
@@ -168,7 +164,7 @@ export class NodeShapeBasedEncoder
 export function encodeFieldShapes(
 	fieldEncoders: readonly KeyedFieldEncoder[],
 	identifiers: DeduplicationTable<string>,
-	shapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,
+	shapes: DeduplicationTable<Shape<EncodedChunkShape>>,
 ): EncodedFieldShape[] | undefined {
 	if (fieldEncoders.length === 0) {
 		return undefined;
@@ -197,14 +193,14 @@ function encodeOptionalIdentifier(
 
 function encodeOptionalFieldShape(
 	encoder: FieldEncoder | undefined,
-	shapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,
+	shapes: DeduplicationTable<Shape<EncodedChunkShape>>,
 ): number | undefined {
 	return encoder === undefined ? undefined : dedupShape(encoder.shape, shapes);
 }
 
 function dedupShape(
-	shape: Shape<EncodedChunkShapeV1OrV2>,
-	shapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,
+	shape: Shape<EncodedChunkShape>,
+	shapes: DeduplicationTable<Shape<EncodedChunkShape>>,
 ): number {
 	return shapes.valueToIndex.get(shape) ?? fail(0xb51 /* missing shape */);
 }

package/src/feature-libraries/forest-summary/codec.ts

@@ -7,9 +7,10 @@ import { assert, oob } from "@fluidframework/core-utils/internal";
 import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal";
 
 import {
-	ClientVersionDispatchingCodecBuilder,
+	VersionDispatchingCodecBuilder,
 	type CodecAndSchema,
 	type CodecWriteOptions,
+	type VersionDispatchingCodec,
 	FluidClientVersion,
 } from "../../codec/index.js";
 import type { FieldKey, ITreeCursorSynchronous } from "../../core/index.js";
@@ -24,7 +25,11 @@ import { ForestFormatVersion, FormatCommon } from "./formatCommon.js";
  * Uses field cursors
  */
 export type FieldSet = ReadonlyMap<FieldKey, ITreeCursorSynchronous>;
-export type ForestCodec = ReturnType<typeof forestCodecBuilder.build>;
+export type ForestCodec = VersionDispatchingCodec<
+	FieldSet,
+	FieldBatchEncodingContext,
+	ForestFormatVersion
+>;
 
 function makeForestSummarizerCodec(
 	options: CodecWriteOptions,
@@ -64,9 +69,9 @@ function makeForestSummarizerCodec(
 }
 
 /**
- * {@link ClientVersionDispatchingCodecBuilder} for forest summarizer codecs.
+ * {@link VersionDispatchingCodecBuilder} for forest summarizer codecs.
  */
-export const forestCodecBuilder = ClientVersionDispatchingCodecBuilder.build("Forest", [
+export const forestCodecBuilder = VersionDispatchingCodecBuilder.build("Forest", [
 	{
 		minVersionForCollab: lowestMinVersionForCollab,
 		formatVersion: ForestFormatVersion.v1,

package/src/feature-libraries/modular-schema/modularChangeTypes.ts

@@ -17,7 +17,7 @@ import type { TreeChunk } from "../chunked-forest/index.js";
 
 import type { CrossFieldTarget } from "./crossFieldQueries.js";
 
-export interface ModularChangeset extends HasFieldChanges {
+export interface ModularChangeset extends Readonly<HasFieldChanges> {
 	/**
 	 * The numerically highest `ChangesetLocalId` used in this changeset.
 	 * If undefined then this changeset contains no IDs.

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

@@ -6,10 +6,7 @@
 import { fail } from "@fluidframework/core-utils/internal";
 import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal";
 
-import {
-	ClientVersionDispatchingCodecBuilder,
-	FluidClientVersion,
-} from "../../codec/index.js";
+import { VersionDispatchingCodecBuilder, FluidClientVersion } from "../../codec/index.js";
 import {
 	SchemaFormatVersion,
 	type TreeNodeSchemaIdentifier,
@@ -100,7 +97,7 @@ function decodeV2(f: FormatV2): TreeStoredSchema {
 /**
  * Creates a codec which performs synchronous monolithic encoding of schema content.
  */
-export const schemaCodecBuilder = ClientVersionDispatchingCodecBuilder.build("Schema", [
+export const schemaCodecBuilder = VersionDispatchingCodecBuilder.build("Schema", [
 	{
 		minVersionForCollab: lowestMinVersionForCollab,
 		formatVersion: SchemaFormatVersion.v1,

package/src/index.ts

@@ -403,5 +403,10 @@ export { FluidSerializableAsTree } from "./serializableDomainSchema.js";
 export { TableSchema, type System_TableSchema } from "./tableSchema.js";
 export { asAlpha, asBeta } from "./api.js";
 
-export { TextAsTree, FormattedTextAsTree } from "./text/index.js";
+export {
+	TextAsTree,
+	FormattedTextAsTree,
+	codePointCount,
+	utf16LengthForCodePoints,
+} from "./text/index.js";
 export { ExtensibleUnionNode } from "./extensibleUnionNode.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.101.1";
+export const pkgVersion = "2.102.0";

package/src/shared-tree/isAuditableFromOutcome.ts

@@ -0,0 +1,34 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
+
+/**
+ * Determines whether a {@link SharedTreeChange} is auditable for HitL purposes
+ * by inspecting the resulting state after the change is applied.
+ *
+ * Returns `false` if any of the following is true:
+ * - The change contains more than one inner change.
+ * - The change contains a schema change.
+ * - The change contains a data change with violated constraints.
+ *
+ * Otherwise returns `true` (including for an empty change, which has nothing
+ * a viewer of the post-apply state would be unable to see).
+ *
+ */
+export function isAuditableFromOutcome(change: SharedTreeChange): boolean {
+	if (change.changes.length > 1) {
+		return false;
+	}
+	for (const inner of change.changes) {
+		if (inner.type === "schema") {
+			return false;
+		}
+		if ((inner.innerChange.constraintViolationCount ?? 0) > 0) {
+			return false;
+		}
+	}
+	return true;
+}

package/src/shared-tree/treeCheckout.ts

@@ -134,6 +134,20 @@ function* collectTreeLabels(node: LabelTree): IterableIterator<unknown> {
 	}
 }
 
+/**
+ * Deep-clones a {@link LabelTree} so the result is independent of the source.
+ * @remarks
+ * Used when capturing the label tree on a revertible so that subsequent mutations
+ * (by the framework or by external listeners reading {@link TransactionLabels.tree})
+ * cannot affect the labels the revertible will emit.
+ */
+function cloneLabelTree(tree: LabelTree): LabelTree {
+	return {
+		label: tree.label,
+		sublabels: tree.sublabels.map(cloneLabelTree),
+	};
+}
+
 /**
  * Builds the labels set for a change event from the label tree.
  * If the tree exists and contains at least one defined label, returns a set of all
@@ -713,6 +727,12 @@ export class TreeCheckout implements ITreeCheckout {
 				const kind = event.type === "append" ? event.kind : CommitKind.Default;
 				const { change, revision } = commit;
 
+				// Snapshot the label tree for this commit before any listener runs, so the captured
+				// value is stable against mutations to `metadata.labels.tree` (which aliases the
+				// live `labelTreeNode`).
+				const commitLabelTree =
+					this.labelTreeNode === undefined ? undefined : cloneLabelTree(this.labelTreeNode);
+
 				const getRevertible = hasSchemaChange(change)
 					? undefined
 					: (onRevertibleDisposed?: (revertible: RevertibleAlpha) => void) => {
@@ -731,6 +751,7 @@ export class TreeCheckout implements ITreeCheckout {
 								kind,
 								this,
 								onRevertibleDisposed,
+								commitLabelTree,
 							);
 							this.revertibleCommitBranches.set(
 								revision,
@@ -1010,6 +1031,8 @@ export class TreeCheckout implements ITreeCheckout {
 	 * @param kind - The {@link CommitKind} that produced this revertible (e.g., Default, Undo, Redo).
 	 * @param checkout - The {@link TreeCheckout} instance this revertible belongs to.
 	 * @param onRevertibleDisposed - Callback function that will be called when the revertible is disposed.
+	 * @param labelTree - The {@link LabelTree} (if any) active when the original commit was produced.
+	 * The revert commit inherits these labels so that commits and their reverts can be associated.
 	 * @returns A {@link RevertibleAlpha} object.
 	 */
 	private createRevertible(
@@ -1017,6 +1040,7 @@ export class TreeCheckout implements ITreeCheckout {
 		kind: CommitKind,
 		checkout: TreeCheckout,
 		onRevertibleDisposed: ((revertible: RevertibleAlpha) => void) | undefined,
+		labelTree: LabelTree | undefined,
 	): RevertibleAlpha {
 		const commitBranches = checkout.revertibleCommitBranches;
 
@@ -1032,7 +1056,7 @@ export class TreeCheckout implements ITreeCheckout {
 					throw new UsageError("Unable to revert a revertible that has been disposed.");
 				}
 
-				const revertMetrics = checkout.revertRevertible(revision, kind);
+				const revertMetrics = checkout.revertRevertible(revision, kind, labelTree);
 				checkout.logger?.sendTelemetryEvent({
 					eventName: TreeCheckout.revertTelemetryEventName,
 					...revertMetrics,
@@ -1062,7 +1086,13 @@ export class TreeCheckout implements ITreeCheckout {
 
 				targetCheckout.revertibleCommitBranches.set(revision, revertibleBranch.fork());
 
-				return this.createRevertible(revision, kind, targetCheckout, onRevertibleDisposed);
+				return this.createRevertible(
+					revision,
+					kind,
+					targetCheckout,
+					onRevertibleDisposed,
+					labelTree,
+				);
 			},
 			dispose: () => {
 				if (revertible.status === RevertibleStatus.Disposed) {
@@ -1323,7 +1353,11 @@ export class TreeCheckout implements ITreeCheckout {
 		this.revertibles.delete(revertible);
 	}
 
-	private revertRevertible(revision: RevisionTag, kind: CommitKind): RevertMetrics {
+	private revertRevertible(
+		revision: RevisionTag,
+		kind: CommitKind,
+		labelTree: LabelTree | undefined,
+	): RevertMetrics {
 		this.editLock.checkUnlocked("Reverting a commit");
 		if (this.transaction.size > 0) {
 			throw new UsageError("Undo is not yet supported during transactions.");
@@ -1366,12 +1400,21 @@ export class TreeCheckout implements ITreeCheckout {
 			);
 		}
 
-		this.#transaction.activeBranch.apply(
-			change,
-			kind === CommitKind.Default || kind === CommitKind.Redo
-				? CommitKind.Undo
-				: CommitKind.Redo,
-		);
+		// Install the original commit's label tree so the revert commit's metadata inherits
+		// the same labels. Reusing the captured tree (rather than wrapping it) ensures
+		// revert-of-revert does not introduce new nesting.
+		const previousLabelTreeNode = this.labelTreeNode;
+		this.labelTreeNode = labelTree;
+		try {
+			this.#transaction.activeBranch.apply(
+				change,
+				kind === CommitKind.Default || kind === CommitKind.Redo
+					? CommitKind.Undo
+					: CommitKind.Redo,
+			);
+		} finally {
+			this.labelTreeNode = previousLabelTreeNode;
+		}
 
 		// Derive some stats about the reversion to return to the caller.
 		let revertAge = 0;

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

@@ -8,7 +8,7 @@ import type { MinimumVersionForCollab } from "@fluidframework/runtime-definition
 import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal";
 
 import {
-	ClientVersionDispatchingCodecBuilder,
+	VersionDispatchingCodecBuilder,
 	type CodecTree,
 	type CodecVersion,
 	type DependentFormatVersion,
@@ -64,11 +64,9 @@ interface EditManagerCodecOptions<TChangeset> extends ICodecOptions {
 }
 
 /**
- * Creates a {@link ClientVersionDispatchingCodecBuilder} encoding for {@link SummaryData}.
+ * Creates a {@link VersionDispatchingCodecBuilder} encoding for {@link SummaryData}.
  */
-export function makeEditManagerCodecBuilder<
-	TChangeset,
->(): ClientVersionDispatchingCodecBuilder<
+export function makeEditManagerCodecBuilder<TChangeset>(): VersionDispatchingCodecBuilder<
 	EditManagerCodecOptions<TChangeset>,
 	SummaryData<TChangeset>,
 	EditManagerEncodingContext,
@@ -137,7 +135,7 @@ export function makeEditManagerCodecBuilder<
 		},
 	];
 
-	return ClientVersionDispatchingCodecBuilder.build(editManagerCodecName, versions);
+	return VersionDispatchingCodecBuilder.build(editManagerCodecName, versions);
 }
 
 /**

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

@@ -8,7 +8,7 @@ import type { MinimumVersionForCollab } from "@fluidframework/runtime-definition
 import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal";
 
 import {
-	ClientVersionDispatchingCodecBuilder,
+	VersionDispatchingCodecBuilder,
 	type CodecTree,
 	type CodecVersion,
 	type DependentFormatVersion,
@@ -58,9 +58,9 @@ interface MessageCodecBuilderOptions<TChangeset> extends ICodecOptions {
 }
 
 /**
- * Creates a {@link ClientVersionDispatchingCodecBuilder} for encoding/decoding messages.
+ * Creates a {@link VersionDispatchingCodecBuilder} for encoding/decoding messages.
  */
-export function makeMessageCodecBuilder<TChangeset>(): ClientVersionDispatchingCodecBuilder<
+export function makeMessageCodecBuilder<TChangeset>(): VersionDispatchingCodecBuilder<
 	MessageCodecBuilderOptions<TChangeset>,
 	DecodedMessage<TChangeset>,
 	MessageEncodingContext,
@@ -129,7 +129,7 @@ export function makeMessageCodecBuilder<TChangeset>(): ClientVersionDispatchingC
 		},
 	];
 
-	return ClientVersionDispatchingCodecBuilder.build(messageCodecName, versions);
+	return VersionDispatchingCodecBuilder.build(messageCodecName, versions);
 }
 
 export function getCodecTreeForMessageFormatWithChange(

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

@@ -120,14 +120,16 @@ export class TreeNodeKernel {
 	#hydrationState: HydrationState;
 
 	/**
-	 * Events registered before hydration.
+	 * Handler for events listeners registered with the kernel.
+	 *
 	 * @remarks
-	 * Since these are usually not used, they are allocated lazily as an optimization.
-	 * The laziness also avoids extra forwarding overhead for events from this kernel's anchor node and also avoids registering for events that are unneeded.
-	 * This means optimizations like skipping processing data in subtrees where no subtreeChanged events are subscribed to would be able to work,
-	 * since the kernel does not unconditionally subscribe to those events (like a design which simply forwards all events would).
+	 * Supports event buffering via {@link withBufferedEvents}.
+	 *
+	 * Allocated lazily on first access to {@link TreeNodeKernel.events}.
+	 * We expect the majority of nodes to never have event listeners registered, so
+	 * deferring construction avoids per-kernel allocations.
 	 */
-	readonly #eventBuffer: KernelEventBuffer;
+	#eventBuffer: KernelEventBuffer | undefined;
 
 	/**
 	 * Create a TreeNodeKernel which can be looked up with {@link getKernel}.
@@ -157,12 +159,9 @@ export class TreeNodeKernel {
 			this.#hydrationState = {
 				innerNode,
 			};
-
-			this.#eventBuffer = new KernelEventBuffer(innerNode.events);
 		} else {
 			// Hydrated case
 			this.#hydrationState = this.createHydratedState(innerNode);
-			this.#eventBuffer = new KernelEventBuffer(innerNode.anchorNode.events);
 		}
 	}
 
@@ -190,8 +189,10 @@ export class TreeNodeKernel {
 
 		this.#hydrationState = this.createHydratedState(inner);
 
-		// Lazily migrate existing event listeners to the anchor node
-		this.#eventBuffer.migrateEventSource(inner.anchorNode.events);
+		// Lazily migrate existing event listeners to the anchor node.
+		// If no one ever subscribed to this kernel's events, the buffer was never allocated
+		// and there is nothing to migrate.
+		this.#eventBuffer?.migrateEventSource(inner.anchorNode.events);
 	}
 
 	private createHydratedState(innerNode: HydratedFlexTreeNode): HydratedState {
@@ -233,6 +234,14 @@ export class TreeNodeKernel {
 	}
 
 	public get events(): Listenable<KernelEvents> {
+		assert(!this.disposed, 0xcfa /* Cannot register events on a disposed node */);
+		// Allocate the buffer on first access. See {@link TreeNodeKernel.#eventBuffer} for rationale.
+		if (this.#eventBuffer === undefined) {
+			const eventSource = isHydrated(this.#hydrationState)
+				? this.#hydrationState.innerNode.anchorNode.events
+				: this.#hydrationState.innerNode.events;
+			this.#eventBuffer = new KernelEventBuffer(eventSource);
+		}
 		return this.#eventBuffer;
 	}
 
@@ -244,7 +253,7 @@ export class TreeNodeKernel {
 				off();
 			}
 		}
-		this.#eventBuffer.dispose();
+		this.#eventBuffer?.dispose();
 		// TODO: go to the context and remove myself from withAnchors
 	}
 
@@ -430,6 +439,8 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 	}
 
 	public on(eventName: keyof KernelEvents, listener: KernelEvents[typeof eventName]): Off {
+		this.#assertNotDisposed();
+
 		// Lazily bind event listeners to the source.
 		// If we do not have any existing listeners for this event, then we need to bind to the source.
 		if (!this.#events.hasListeners(eventName)) {
@@ -446,7 +457,10 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 		}
 
 		this.#events.on(eventName, listener);
-		return () => this.off(eventName, listener);
+		// Return a bound method instead of an arrow closure. A bound function captures
+		// (target, thisArg, ...boundArgs) in a fixed shape that V8 can optimize more
+		// uniformly than a closure that captures its lexical context.
+		return this.off.bind(this, eventName, listener);
 	}
 
 	public off(eventName: keyof KernelEvents, listener: KernelEvents[typeof eventName]): void {

package/src/text/codePointUtils.ts

@@ -0,0 +1,81 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+/**
+ * Returns the number of Unicode code points in `value`.
+ * @remarks
+ * Use this to translate a JavaScript string length (which is in UTF-16 code units) into
+ * the atom/code-point space used by {@link TextAsTree}.
+ *
+ * @example
+ * ```typescript
+ * codePointCount("");     // 0
+ * codePointCount("abc");  // 3
+ * codePointCount("a😀b"); // 3 — emoji is one code point, but "a😀b".length === 4 (UTF-16 surrogate pair)
+ * ```
+ *
+ * @internal
+ */
+export function codePointCount(value: string): number {
+	// Iterate instead of spreading to avoid allocating an intermediate array.
+	let count = 0;
+	for (const _ of value) {
+		count++;
+	}
+	return count;
+}
+
+/**
+ * Returns the number of UTF-16 code units occupied by the first `count` Unicode code points in `value`,
+ * starting at UTF-16 index `start`.
+ * @remarks
+ * Use this to translate {@link TextAsTree}-space counts (code points) into JavaScript string indices (UTF-16).
+ * One code point outside the Basic Multilingual Plane (e.g. most emoji) occupies two UTF-16 code units.
+ *
+ * Validates that the requested `count` code points are fully consumable from `start`; silent truncation
+ * would misalign delta offsets applied to strings rather than surface the drift to the caller.
+ *
+ * @example
+ * ```typescript
+ * utf16LengthForCodePoints("abc", 0, 3);  // 3 — three single-unit characters
+ * utf16LengthForCodePoints("a😀b", 0, 3); // 4 — a (1) + 😀 (2) + b (1)
+ * utf16LengthForCodePoints("a😀b", 1, 1); // 2 — just the emoji
+ * utf16LengthForCodePoints("abc", 0, 0);  // 0 — no code points requested
+ * ```
+ *
+ * @param value - The string to measure.
+ * @param start - The UTF-16 index in `value` to start measuring from. Must be in `[0, value.length]`.
+ * @param count - The number of Unicode code points to measure. Must be non-negative, and there must
+ * be at least `count` code points available in `value` starting at `start`.
+ * @throws A {@link @fluidframework/telemetry-utils#UsageError} if `start` is out of range,
+ * `count` is negative, or fewer than `count` code points are available from `start`.
+ * @internal
+ */
+export function utf16LengthForCodePoints(value: string, start: number, count: number): number {
+	if (start < 0 || start > value.length) {
+		throw new UsageError(
+			`start (${start}) must be within [0, ${value.length}] (value.length).`,
+		);
+	}
+	if (count < 0) {
+		throw new UsageError(`count (${count}) must be non-negative.`);
+	}
+	let utf16 = 0;
+	let counted = 0;
+	while (counted < count && start + utf16 < value.length) {
+		// Code points above 0xFFFF are encoded in UTF-16 as a surrogate pair (2 units);
+		// everything else takes a single UTF-16 unit.
+		utf16 += (value.codePointAt(start + utf16) ?? 0) > 0xffff ? 2 : 1;
+		counted++;
+	}
+	if (counted !== count) {
+		throw new UsageError(
+			`count (${count}) exceeds the ${counted} code point(s) available from start (${start}) in a value of length ${value.length}.`,
+		);
+	}
+	return utf16;
+}

package/src/text/index.ts

@@ -5,3 +5,4 @@
 
 export { TextAsTree } from "./textDomain.js";
 export { FormattedTextAsTree } from "./textDomainFormatted.js";
+export { codePointCount, utf16LengthForCodePoints } from "./codePointUtils.js";