@fluidframework/tree 2.101.1 → 2.103.0

package/dist/feature-libraries/chunked-forest/codec/nodeEncoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodeEncoder.d.ts","sourceRoot":"","sources":["../../../../src/feature-libraries/chunked-forest/codec/nodeEncoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAEN,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAG7B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,KAAK,YAAY,EAAmB,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAEhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACX,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,EACjB,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,qBAAa,qBACZ,SAAQ,KAAK,CAAC,uBAAuB,CACrC,YAAW,WAAW;aASL,IAAI,EAAE,SAAS,GAAG,wBAAwB;aAC1C,KAAK,EAAE,iBAAiB;IACxC;;;;;;;;;;OAUG;aACa,wBAAwB,EAAE,SAAS,iBAAiB,EAAE;IACtE;;;OAGG;aACa,kBAAkB,EAAE,SAAS,GAAG,YAAY;IAzB7D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAgB;gBAGpC,IAAI,EAAE,SAAS,GAAG,wBAAwB,EAC1C,KAAK,EAAE,iBAAiB;IACxC;;;;;;;;;;OAUG;IACa,wBAAwB,EAAE,SAAS,iBAAiB,EAAE;IACtE;;;OAGG;IACa,kBAAkB,EAAE,SAAS,GAAG,YAAY;IAM7D,OAAO,CAAC,gBAAgB;IAqBjB,UAAU,CAChB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,YAAY,CAAC,uBAAuB,CAAC,GACjD,IAAI;IAgCA,WAAW,CACjB,WAAW,EAAE,kBAAkB,CAAC,MAAM,CAAC,EACvC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,GACxD,uBAAuB;IAWnB,mCAAmC,CACzC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,EAC5B,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,uBAAuB,CAAC,KAAK,IAAI,GAC9D,IAAI;IAeP,IAAW,KAAK,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAEjD;CACD;AAED,wBAAgB,iBAAiB,CAChC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,WAAW,EAAE,kBAAkB,CAAC,MAAM,CAAC,EACvC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,GACxD,iBAAiB,EAAE,GAAG,SAAS,CAUjC"}
+{"version":3,"file":"nodeEncoder.d.ts","sourceRoot":"","sources":["../../../../src/feature-libraries/chunked-forest/codec/nodeEncoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAEN,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAG7B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,KAAK,YAAY,EAAmB,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAEhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACX,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK,CAAC,iBAAiB,CAAE,YAAW,WAAW;aAQxE,IAAI,EAAE,SAAS,GAAG,wBAAwB;aAC1C,KAAK,EAAE,iBAAiB;IACxC;;;;;;;;;;OAUG;aACa,wBAAwB,EAAE,SAAS,iBAAiB,EAAE;IACtE;;;OAGG;aACa,kBAAkB,EAAE,SAAS,GAAG,YAAY;IAzB7D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAgB;gBAGpC,IAAI,EAAE,SAAS,GAAG,wBAAwB,EAC1C,KAAK,EAAE,iBAAiB;IACxC;;;;;;;;;;OAUG;IACa,wBAAwB,EAAE,SAAS,iBAAiB,EAAE;IACtE;;;OAGG;IACa,kBAAkB,EAAE,SAAS,GAAG,YAAY;IAM7D,OAAO,CAAC,gBAAgB;IAoBjB,UAAU,CAChB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,YAAY,CAAC,iBAAiB,CAAC,GAC3C,IAAI;IAgCA,WAAW,CACjB,WAAW,EAAE,kBAAkB,CAAC,MAAM,CAAC,EACvC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,GAClD,iBAAiB;IAWb,mCAAmC,CACzC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,EAC5B,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,iBAAiB,CAAC,KAAK,IAAI,GACxD,IAAI;IAeP,IAAW,KAAK,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAE3C;CACD;AAED,wBAAgB,iBAAiB,CAChC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,WAAW,EAAE,kBAAkB,CAAC,MAAM,CAAC,EACvC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,GAClD,iBAAiB,EAAE,GAAG,SAAS,CAUjC"}

package/dist/feature-libraries/chunked-forest/codec/nodeEncoder.js

@@ -54,8 +54,7 @@ class NodeShapeBasedEncoder extends chunkEncodingGeneric_js_1.Shape {
                     // 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 || (0, internal_2.isFinalId)(opSpaceId)) {
                         return opSpaceId;
                     }
                 }

package/dist/feature-libraries/chunked-forest/codec/nodeEncoder.js.map

@@ -1 +1 @@
-{"version":3,"file":"nodeEncoder.js","sourceRoot":"","sources":["../../../../src/feature-libraries/chunked-forest/codec/nodeEncoder.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert, fail } from \"@fluidframework/core-utils/internal\";\nimport { isStableId } from \"@fluidframework/id-compressor/internal\";\n\nimport {\n\ttype FieldKey,\n\ttype ITreeCursorSynchronous,\n\ttype TreeNodeSchemaIdentifier,\n\tforEachField,\n\ttype Value,\n} from \"../../../core/index.js\";\nimport { brand } from \"../../../util/index.js\";\n\nimport type { Counter, DeduplicationTable } from \"./chunkCodecUtilities.js\";\nimport { type BufferFormat, IdentifierToken, Shape } from \"./chunkEncodingGeneric.js\";\nimport {\n\ttype EncoderContext,\n\ttype FieldEncoder,\n\ttype KeyedFieldEncoder,\n\ttype NodeEncoder,\n\tencodeValue,\n} from \"./compressedEncode.js\";\nimport type {\n\tEncodedChunkShapeV1OrV2,\n\tEncodedFieldShape,\n\tEncodedValueShape,\n} from \"./format/index.js\";\n\n/**\n * Encodes a node with the {@link EncodedNodeShape} shape.\n * @remarks\n * The fact this is also a Shape is an implementation detail of the encoder: that allows the shape it uses to be itself,\n * which is an easy way to keep all the related code together without extra objects.\n */\nexport class NodeShapeBasedEncoder\n\textends Shape<EncodedChunkShapeV1OrV2>\n\timplements NodeEncoder\n{\n\t/**\n\t * Set of keys for fields that are encoded using {@link NodeShapeBasedEncoder.specializedFieldEncoders}.\n\t * TODO: Ensure uniform chunks, encoding and identifier generation sort fields the same.\n\t */\n\tprivate readonly specializedFieldKeys: Set<FieldKey>;\n\n\tpublic constructor(\n\t\tpublic readonly type: undefined | TreeNodeSchemaIdentifier,\n\t\tpublic readonly value: EncodedValueShape,\n\t\t/**\n\t\t * Encoders for a specific set of fields, by key, in the order they will be encoded.\n\t\t * These are fields for which specialized encoding is provided as an optimization.\n\t\t * Using these for a given field instead of falling back to {@link NodeShapeBasedEncoder.specializedFieldEncoders} is often more efficient:\n\t\t * this avoids the need to explicitly include the key and shape in the encoded data for each node instance.\n\t\t * Instead, this information is here, and thus is encoded only once as part of the node shape.\n\t\t * These encoders will be used, even if the field they apply to is empty (which can add overhead for fields which are usually empty).\n\t\t *\n\t\t * Any fields not included here will be encoded using {@link NodeShapeBasedEncoder.otherFieldsEncoder}.\n\t\t * If {@link NodeShapeBasedEncoder.otherFieldsEncoder} is undefined, then this must handle all non-empty fields.\n\t\t */\n\t\tpublic readonly specializedFieldEncoders: readonly KeyedFieldEncoder[],\n\t\t/**\n\t\t * Encoder for all other fields that are not in {@link NodeShapeBasedEncoder.specializedFieldEncoders}. These fields must\n\t\t * be encoded after the specialized fields.\n\t\t */\n\t\tpublic readonly otherFieldsEncoder: undefined | FieldEncoder,\n\t) {\n\t\tsuper();\n\t\tthis.specializedFieldKeys = new Set(this.specializedFieldEncoders.map((f) => f.key));\n\t}\n\n\tprivate getValueToEncode(cursor: ITreeCursorSynchronous, context: EncoderContext): Value {\n\t\tif (this.value === 0) {\n\t\t\tassert(typeof cursor.value === \"string\", 0x9aa /* identifier must be type string */);\n\t\t\tif (isStableId(cursor.value)) {\n\t\t\t\tconst sessionSpaceCompressedId = context.idCompressor.tryRecompress(cursor.value);\n\t\t\t\tif (sessionSpaceCompressedId !== undefined) {\n\t\t\t\t\tconst opSpaceId = context.idCompressor.normalizeToOpSpace(sessionSpaceCompressedId);\n\t\t\t\t\t// Summaries can only contain finalized op-space ids unless they also include the originator's session id somewhere.\n\t\t\t\t\t// This is not the case for forest summaries at the time of writing, so non-finalized ids are instead written using\n\t\t\t\t\t// their long form (by falling through to the original cursor value).\n\t\t\t\t\t// 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.\n\t\t\t\t\t// TODO: isFinalId should probably be exported from id-compressor and that could be used to do the narrowing here.\n\t\t\t\t\tif (!context.isSummary || opSpaceId >= 0) {\n\t\t\t\t\t\treturn opSpaceId;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn cursor.value;\n\t}\n\n\tpublic encodeNode(\n\t\tcursor: ITreeCursorSynchronous,\n\t\tcontext: EncoderContext,\n\t\toutputBuffer: BufferFormat<EncodedChunkShapeV1OrV2>,\n\t): void {\n\t\tif (this.type === undefined) {\n\t\t\toutputBuffer.push(new IdentifierToken(cursor.type));\n\t\t} else {\n\t\t\tassert(cursor.type === this.type, 0x741 /* type must match shape */);\n\t\t}\n\t\tencodeValue(this.getValueToEncode(cursor, context), this.value, outputBuffer);\n\t\tfor (const fieldEncoder of this.specializedFieldEncoders) {\n\t\t\tcursor.enterField(brand(fieldEncoder.key));\n\t\t\tfieldEncoder.encoder.encodeField(cursor, context, outputBuffer);\n\t\t\tcursor.exitField();\n\t\t}\n\n\t\tconst otherFieldsBuffer: BufferFormat<EncodedChunkShapeV1OrV2> = [];\n\n\t\tforEachField(cursor, () => {\n\t\t\tconst key = cursor.getFieldKey();\n\t\t\tif (!this.specializedFieldKeys.has(key)) {\n\t\t\t\tassert(\n\t\t\t\t\tthis.otherFieldsEncoder !== undefined,\n\t\t\t\t\t0x742 /* had extra local fields when shape does not support them */,\n\t\t\t\t);\n\t\t\t\totherFieldsBuffer.push(new IdentifierToken(key));\n\t\t\t\tthis.otherFieldsEncoder.encodeField(cursor, context, otherFieldsBuffer);\n\t\t\t}\n\t\t});\n\n\t\tif (this.otherFieldsEncoder !== undefined) {\n\t\t\toutputBuffer.push(otherFieldsBuffer);\n\t\t}\n\t}\n\n\tpublic encodeShape(\n\t\tidentifiers: DeduplicationTable<string>,\n\t\tshapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,\n\t): EncodedChunkShapeV1OrV2 {\n\t\treturn {\n\t\t\tc: {\n\t\t\t\ttype: encodeOptionalIdentifier(this.type, identifiers),\n\t\t\t\tvalue: this.value,\n\t\t\t\tfields: encodeFieldShapes(this.specializedFieldEncoders, identifiers, shapes),\n\t\t\t\textraFields: encodeOptionalFieldShape(this.otherFieldsEncoder, shapes),\n\t\t\t},\n\t\t};\n\t}\n\n\tpublic countReferencedShapesAndIdentifiers(\n\t\tidentifiers: Counter<string>,\n\t\tshapeDiscovered: (shape: Shape<EncodedChunkShapeV1OrV2>) => void,\n\t): void {\n\t\tif (this.type !== undefined) {\n\t\t\tidentifiers.add(this.type);\n\t\t}\n\n\t\tfor (const fieldEncoder of this.specializedFieldEncoders) {\n\t\t\tidentifiers.add(fieldEncoder.key);\n\t\t\tshapeDiscovered(fieldEncoder.encoder.shape);\n\t\t}\n\n\t\tif (this.otherFieldsEncoder !== undefined) {\n\t\t\tshapeDiscovered(this.otherFieldsEncoder.shape);\n\t\t}\n\t}\n\n\tpublic get shape(): Shape<EncodedChunkShapeV1OrV2> {\n\t\treturn this;\n\t}\n}\n\nexport function encodeFieldShapes(\n\tfieldEncoders: readonly KeyedFieldEncoder[],\n\tidentifiers: DeduplicationTable<string>,\n\tshapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,\n): EncodedFieldShape[] | undefined {\n\tif (fieldEncoders.length === 0) {\n\t\treturn undefined;\n\t}\n\treturn fieldEncoders.map((fieldEncoder) => [\n\t\t// key\n\t\tencodeIdentifier(fieldEncoder.key, identifiers),\n\t\t// shape\n\t\tshapes.valueToIndex.get(fieldEncoder.encoder.shape) ?? fail(0xb50 /* missing shape */),\n\t]);\n}\n\nfunction encodeIdentifier(\n\tidentifier: string,\n\tidentifiers: DeduplicationTable<string>,\n): string | number {\n\treturn identifiers.valueToIndex.get(identifier) ?? identifier;\n}\n\nfunction encodeOptionalIdentifier(\n\tidentifier: string | undefined,\n\tidentifiers: DeduplicationTable<string>,\n): string | number | undefined {\n\treturn identifier === undefined ? undefined : encodeIdentifier(identifier, identifiers);\n}\n\nfunction encodeOptionalFieldShape(\n\tencoder: FieldEncoder | undefined,\n\tshapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,\n): number | undefined {\n\treturn encoder === undefined ? undefined : dedupShape(encoder.shape, shapes);\n}\n\nfunction dedupShape(\n\tshape: Shape<EncodedChunkShapeV1OrV2>,\n\tshapes: DeduplicationTable<Shape<EncodedChunkShapeV1OrV2>>,\n): number {\n\treturn shapes.valueToIndex.get(shape) ?? fail(0xb51 /* missing shape */);\n}\n"]}
+{"version":3,"file":"nodeEncoder.js","sourceRoot":"","sources":["../../../../src/feature-libraries/chunked-forest/codec/nodeEncoder.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert, fail } from \"@fluidframework/core-utils/internal\";\nimport { isFinalId, isStableId } from \"@fluidframework/id-compressor/internal\";\n\nimport {\n\ttype FieldKey,\n\ttype ITreeCursorSynchronous,\n\ttype TreeNodeSchemaIdentifier,\n\tforEachField,\n\ttype Value,\n} from \"../../../core/index.js\";\nimport { brand } from \"../../../util/index.js\";\n\nimport type { Counter, DeduplicationTable } from \"./chunkCodecUtilities.js\";\nimport { type BufferFormat, IdentifierToken, Shape } from \"./chunkEncodingGeneric.js\";\nimport {\n\ttype EncoderContext,\n\ttype FieldEncoder,\n\ttype KeyedFieldEncoder,\n\ttype NodeEncoder,\n\tencodeValue,\n} from \"./compressedEncode.js\";\nimport type {\n\tEncodedChunkShape,\n\tEncodedFieldShape,\n\tEncodedValueShape,\n} from \"./format/index.js\";\n\n/**\n * Encodes a node with the {@link EncodedNodeShape} shape.\n * @remarks\n * The fact this is also a Shape is an implementation detail of the encoder: that allows the shape it uses to be itself,\n * which is an easy way to keep all the related code together without extra objects.\n */\nexport class NodeShapeBasedEncoder extends Shape<EncodedChunkShape> implements NodeEncoder {\n\t/**\n\t * Set of keys for fields that are encoded using {@link NodeShapeBasedEncoder.specializedFieldEncoders}.\n\t * TODO: Ensure uniform chunks, encoding and identifier generation sort fields the same.\n\t */\n\tprivate readonly specializedFieldKeys: Set<FieldKey>;\n\n\tpublic constructor(\n\t\tpublic readonly type: undefined | TreeNodeSchemaIdentifier,\n\t\tpublic readonly value: EncodedValueShape,\n\t\t/**\n\t\t * Encoders for a specific set of fields, by key, in the order they will be encoded.\n\t\t * These are fields for which specialized encoding is provided as an optimization.\n\t\t * Using these for a given field instead of falling back to {@link NodeShapeBasedEncoder.specializedFieldEncoders} is often more efficient:\n\t\t * this avoids the need to explicitly include the key and shape in the encoded data for each node instance.\n\t\t * Instead, this information is here, and thus is encoded only once as part of the node shape.\n\t\t * These encoders will be used, even if the field they apply to is empty (which can add overhead for fields which are usually empty).\n\t\t *\n\t\t * Any fields not included here will be encoded using {@link NodeShapeBasedEncoder.otherFieldsEncoder}.\n\t\t * If {@link NodeShapeBasedEncoder.otherFieldsEncoder} is undefined, then this must handle all non-empty fields.\n\t\t */\n\t\tpublic readonly specializedFieldEncoders: readonly KeyedFieldEncoder[],\n\t\t/**\n\t\t * Encoder for all other fields that are not in {@link NodeShapeBasedEncoder.specializedFieldEncoders}. These fields must\n\t\t * be encoded after the specialized fields.\n\t\t */\n\t\tpublic readonly otherFieldsEncoder: undefined | FieldEncoder,\n\t) {\n\t\tsuper();\n\t\tthis.specializedFieldKeys = new Set(this.specializedFieldEncoders.map((f) => f.key));\n\t}\n\n\tprivate getValueToEncode(cursor: ITreeCursorSynchronous, context: EncoderContext): Value {\n\t\tif (this.value === 0) {\n\t\t\tassert(typeof cursor.value === \"string\", 0x9aa /* identifier must be type string */);\n\t\t\tif (isStableId(cursor.value)) {\n\t\t\t\tconst sessionSpaceCompressedId = context.idCompressor.tryRecompress(cursor.value);\n\t\t\t\tif (sessionSpaceCompressedId !== undefined) {\n\t\t\t\t\tconst opSpaceId = context.idCompressor.normalizeToOpSpace(sessionSpaceCompressedId);\n\t\t\t\t\t// Summaries can only contain finalized op-space ids unless they also include the originator's session id somewhere.\n\t\t\t\t\t// This is not the case for forest summaries at the time of writing, so non-finalized ids are instead written using\n\t\t\t\t\t// their long form (by falling through to the original cursor value).\n\t\t\t\t\t// 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.\n\t\t\t\t\tif (!context.isSummary || isFinalId(opSpaceId)) {\n\t\t\t\t\t\treturn opSpaceId;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn cursor.value;\n\t}\n\n\tpublic encodeNode(\n\t\tcursor: ITreeCursorSynchronous,\n\t\tcontext: EncoderContext,\n\t\toutputBuffer: BufferFormat<EncodedChunkShape>,\n\t): void {\n\t\tif (this.type === undefined) {\n\t\t\toutputBuffer.push(new IdentifierToken(cursor.type));\n\t\t} else {\n\t\t\tassert(cursor.type === this.type, 0x741 /* type must match shape */);\n\t\t}\n\t\tencodeValue(this.getValueToEncode(cursor, context), this.value, outputBuffer);\n\t\tfor (const fieldEncoder of this.specializedFieldEncoders) {\n\t\t\tcursor.enterField(brand(fieldEncoder.key));\n\t\t\tfieldEncoder.encoder.encodeField(cursor, context, outputBuffer);\n\t\t\tcursor.exitField();\n\t\t}\n\n\t\tconst otherFieldsBuffer: BufferFormat<EncodedChunkShape> = [];\n\n\t\tforEachField(cursor, () => {\n\t\t\tconst key = cursor.getFieldKey();\n\t\t\tif (!this.specializedFieldKeys.has(key)) {\n\t\t\t\tassert(\n\t\t\t\t\tthis.otherFieldsEncoder !== undefined,\n\t\t\t\t\t0x742 /* had extra local fields when shape does not support them */,\n\t\t\t\t);\n\t\t\t\totherFieldsBuffer.push(new IdentifierToken(key));\n\t\t\t\tthis.otherFieldsEncoder.encodeField(cursor, context, otherFieldsBuffer);\n\t\t\t}\n\t\t});\n\n\t\tif (this.otherFieldsEncoder !== undefined) {\n\t\t\toutputBuffer.push(otherFieldsBuffer);\n\t\t}\n\t}\n\n\tpublic encodeShape(\n\t\tidentifiers: DeduplicationTable<string>,\n\t\tshapes: DeduplicationTable<Shape<EncodedChunkShape>>,\n\t): EncodedChunkShape {\n\t\treturn {\n\t\t\tc: {\n\t\t\t\ttype: encodeOptionalIdentifier(this.type, identifiers),\n\t\t\t\tvalue: this.value,\n\t\t\t\tfields: encodeFieldShapes(this.specializedFieldEncoders, identifiers, shapes),\n\t\t\t\textraFields: encodeOptionalFieldShape(this.otherFieldsEncoder, shapes),\n\t\t\t},\n\t\t};\n\t}\n\n\tpublic countReferencedShapesAndIdentifiers(\n\t\tidentifiers: Counter<string>,\n\t\tshapeDiscovered: (shape: Shape<EncodedChunkShape>) => void,\n\t): void {\n\t\tif (this.type !== undefined) {\n\t\t\tidentifiers.add(this.type);\n\t\t}\n\n\t\tfor (const fieldEncoder of this.specializedFieldEncoders) {\n\t\t\tidentifiers.add(fieldEncoder.key);\n\t\t\tshapeDiscovered(fieldEncoder.encoder.shape);\n\t\t}\n\n\t\tif (this.otherFieldsEncoder !== undefined) {\n\t\t\tshapeDiscovered(this.otherFieldsEncoder.shape);\n\t\t}\n\t}\n\n\tpublic get shape(): Shape<EncodedChunkShape> {\n\t\treturn this;\n\t}\n}\n\nexport function encodeFieldShapes(\n\tfieldEncoders: readonly KeyedFieldEncoder[],\n\tidentifiers: DeduplicationTable<string>,\n\tshapes: DeduplicationTable<Shape<EncodedChunkShape>>,\n): EncodedFieldShape[] | undefined {\n\tif (fieldEncoders.length === 0) {\n\t\treturn undefined;\n\t}\n\treturn fieldEncoders.map((fieldEncoder) => [\n\t\t// key\n\t\tencodeIdentifier(fieldEncoder.key, identifiers),\n\t\t// shape\n\t\tshapes.valueToIndex.get(fieldEncoder.encoder.shape) ?? fail(0xb50 /* missing shape */),\n\t]);\n}\n\nfunction encodeIdentifier(\n\tidentifier: string,\n\tidentifiers: DeduplicationTable<string>,\n): string | number {\n\treturn identifiers.valueToIndex.get(identifier) ?? identifier;\n}\n\nfunction encodeOptionalIdentifier(\n\tidentifier: string | undefined,\n\tidentifiers: DeduplicationTable<string>,\n): string | number | undefined {\n\treturn identifier === undefined ? undefined : encodeIdentifier(identifier, identifiers);\n}\n\nfunction encodeOptionalFieldShape(\n\tencoder: FieldEncoder | undefined,\n\tshapes: DeduplicationTable<Shape<EncodedChunkShape>>,\n): number | undefined {\n\treturn encoder === undefined ? undefined : dedupShape(encoder.shape, shapes);\n}\n\nfunction dedupShape(\n\tshape: Shape<EncodedChunkShape>,\n\tshapes: DeduplicationTable<Shape<EncodedChunkShape>>,\n): number {\n\treturn shapes.valueToIndex.get(shape) ?? fail(0xb51 /* missing shape */);\n}\n"]}

package/dist/feature-libraries/chunked-forest/uniformChunk.d.ts

@@ -57,6 +57,15 @@ export declare class TreeShape {
     readonly fields: ReadonlyMap<FieldKey, OffsetShape>;
     readonly fieldsOffsetArray: readonly OffsetShape[];
     readonly valuesPerTopLevelNode: number;
+    /**
+     * Information about every node in this shape.
+     * The root is first, and all indexes it uses to refer to other nodes are indexes into this array.
+     * Beyond that the ordering is an implementation detail of this shape.
+     * @remarks
+     * Use of this in contexts where there might be multiple top-level nodes requires some additional care.
+     * For example {@link Cursor} derives each node's actual position info from this shared
+     * array plus the node's top-level index within the chunk.
+     */
     readonly positions: readonly NodePositionInfo[];
     /**
      * Whether chunks using this shape (including any descendant leaf within it) may contain values compressed by the {@link UniformChunk.idCompressor}.
@@ -89,16 +98,16 @@ export declare class TreeShape {
 /**
  * The shape (see `TreeShape`) of a sequence of trees, all with the same shape (like `FieldShape`, but without a field key).
  *
- * This shape is optimized (by caching derived data like the positions array),
- * so that when paired with a value array it can be efficiently traversed like a tree by an {@link ITreeCursorSynchronous}.
- * See {@link uniformChunk} for how to do this.
+ * @remarks
+ * Paired with a value array, this lets a {@link UniformChunk} be traversed like a tree by an
+ * {@link ITreeCursorSynchronous}. The {@link Cursor} derives each node's position info from the
+ * shared {@link TreeShape.positions} plus the node's top-level index.
  *
  * TODO: consider storing shape information in WASM
  */
 export declare class ChunkShape {
     readonly treeShape: TreeShape;
     readonly topLevelLength: number;
-    readonly positions: readonly (NodePositionInfo | undefined)[];
     constructor(treeShape: TreeShape, topLevelLength: number);
     equals(other: ChunkShape): boolean;
 }
@@ -122,7 +131,7 @@ declare class OffsetShape {
     constructor(shape: TreeShape, topLevelLength: number, offset: number, key: FieldKey, indexOfParentField: number | undefined);
 }
 /**
- * Information about a node at a specific position within a uniform chunk.
+ * Information about a node at a specific position within one top-level tree of a {@link TreeShape}.
  */
 declare class NodePositionInfo implements UpPath {
     readonly parent: NodePositionInfo | undefined;
@@ -134,13 +143,15 @@ declare class NodePositionInfo implements UpPath {
     readonly topLevelLength: number;
     readonly valueOffset: number;
     /**
-     * @param parent - TODO
-     * @param parentField - TODO
+     * @param parent - The parent node's {@link NodePositionInfo} or `undefined` for a root.
+     * @param parentField - The {@link FieldKey} of the field this node occupies within its parent.
      * @param parentIndex - indexWithinParentField
-     * @param indexOfParentField - which field of the parent `parentIndex` is indexing into to locate this.
-     * @param indexOfParentPosition - Index of parent NodePositionInfo in positions array. TODO: use offsets to avoid copying at top level?
+     * @param indexOfParentField - Which field of the parent `parentIndex` is indexing into to locate this.
+     * @param indexOfParentPosition - Index of this node's parent in {@link TreeShape.positions}
      * @param shape - Shape of the top level sequence this node is part of
-     * @param valueOffset - TODO
+     * @param topLevelLength - Number of siblings in this node's field. For a root this is unused
+     * @param valueOffset - Offset of this node's value within one top-level tree's slice of the chunk's flat `values` array;
+     * only valid when `shape.hasValue` (otherwise it's where the value would have gone, and should not be used to read a value).
      */
     constructor(parent: NodePositionInfo | undefined, // TODO; general UpPath to allow prefixing here?
     parentField: FieldKey, parentIndex: number, indexOfParentField: number | undefined, indexOfParentPosition: number | undefined, shape: TreeShape, // Shape of sequence that contains this node (top level is parent of this node)
@@ -149,14 +160,25 @@ declare class NodePositionInfo implements UpPath {
 /**
  * The cursor implementation for `UniformChunk`.
  *
- * Works by tracking its location in the chunk's `positions` array.
+ * @remarks
+ * Tracks a flat `positionIndex` and derives each node's position info from the shape's shared
+ * {@link TreeShape.positions} plus the node's top-level index.
  */
 declare class Cursor extends SynchronousCursor implements ChunkedCursor {
     private readonly chunk;
     private positionIndex;
+    /** Position info for the current node, or `undefined` when in root field. */
     private nodePositionInfo;
+    /** Which top-level node of the chunk the current position is within. Valid when nodePositionInfo !== undefined. */
+    private topLevelIndex;
+    /** The chunk's shape. */
     private readonly shape;
-    private readonly positions;
+    /** The chunk's per-tree shape (shape of each top-level tree). */
+    private readonly treeShape;
+    /** Number of positions in one top-level tree (treeShape.positions.length). */
+    private readonly nodeLength;
+    /** Number of values per top-level node (treeShape.valuesPerTopLevelNode). */
+    private readonly stride;
     mode: CursorLocationType;
     private fieldKey?;
     private indexOfField;
@@ -166,12 +188,32 @@ declare class Cursor extends SynchronousCursor implements ChunkedCursor {
     fork(): Cursor;
     /**
      * Change the current node within the chunk.
+     *
+     * @param positionIndex - flat position index of the newly selected node. This is NOT an index
+     * within a field, and is not bounds checked.
+     *
+     * @remarks
+     * Decomposes the index into {@link Cursor.topLevelIndex} and {@link Cursor.nodePositionInfo}.
      * See `nodeInfo` for getting data about the current node.
      *
-     * @param positionIndex - index of the position of the newly selected node in `positions`.
-     * This is NOT an index within a field, and is not bounds checked.
      */
     private moveToPosition;
+    /**
+     * Decode a flat `positionIndex` into its components.
+     *
+     * @param positionIndex - flat position index of the node to decode. Must be greater than 0;
+     * @returns the node's index within {@link TreeShape.positions} (`withinTree`), which top-level
+     * tree holds it (`topLevelIndex`), and the corresponding shared {@link NodePositionInfo} (`info`).
+     */
+    private decodePosition;
+    /**
+     * Build a standalone {@link UpPath} for the node at `positionIndex`. O(depth) allocation.
+     *
+     * @remarks
+     * walks the shared per-tree {@link TreeShape.positions} and applies the top-level index
+     * at each level. Mirrors how the `BasicChunk` cursor allocates paths.
+     */
+    private materializePath;
     /**
      * Gets information about the current node.
      *
@@ -199,6 +241,16 @@ declare class Cursor extends SynchronousCursor implements ChunkedCursor {
     getPath(prefix?: PathRootPrefix): UpPath | undefined;
     get fieldIndex(): number;
     readonly chunkStart: number;
+    /**
+     * Number of nodes in `info`'s field including `info` itself.
+     *
+     * @remarks
+     * For top-level nodes this is the chunk's `topLevelLength`, read from the chunk
+     * rather than the node, so the shared per-tree {@link TreeShape.positions} stays independent of
+     * chunk length; the root entry's own `topLevelLength` field is unused. Nested nodes use the
+     * field length stored on the node.
+     */
+    private siblingCount;
     get chunkLength(): number;
     seekNodes(offset: number): boolean;
     nextNode(): boolean;

package/dist/feature-libraries/chunked-forest/uniformChunk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uniformChunk.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/uniformChunk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAA4B,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE7F,OAAO,EACN,kBAAkB,EAClB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,WAAW,EAEX,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAwB,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAA+B,MAAM,uBAAuB,CAAC;AAEvF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,CAE9E;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,oBAAqB,YAAW,SAAS;IASlE,KAAK,EAAE,UAAU;IACjB,MAAM,EAAE,SAAS,EAAE;IATpB,YAAY,EAAE,SAAS,GAAG,aAAa,CAAC;IAC/C;;;;;OAKG;gBAEK,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,SAAS,EAAE,EAC1B,YAAY,CAAC,EAAE,aAAa;IAU7B,IAAW,cAAc,IAAI,MAAM,CAElC;IAEM,KAAK,IAAI,YAAY;IAIrB,MAAM,IAAI,MAAM;IAIvB,SAAS,CAAC,cAAc,IAAI,IAAI;CAChC;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAmBhE;;;;;;;GAOG;AACH,qBAAa,SAAS;aAmCJ,IAAI,EAAE,wBAAwB;aAC9B,QAAQ,EAAE,OAAO;aACjB,WAAW,EAAE,SAAS,UAAU,EAAE;IApCnD,SAAgB,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC3D,SAAgB,iBAAiB,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1D,SAAgB,qBAAqB,EAAE,MAAM,CAAC;IAG9C,SAAgB,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAEvD;;;;;;;OAOG;IACH,SAAgB,uBAAuB,EAAE,OAAO,CAAC;IAEjD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsC;IAEtE;;;;;;;;OAQG;gBAEc,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,EAAE,OAAO,EACjB,WAAW,EAAE,SAAS,UAAU,EAAE,EAClD,qBAAqB,GAAE,OAAe;IAoChC,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO;IAmBjC,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU;CAU7D;AAgCD;;;;;;;;GAQG;AACH,qBAAa,UAAU;aAIL,SAAS,EAAE,SAAS;aACpB,cAAc,EAAE,MAAM;IAJvC,SAAgB,SAAS,EAAE,SAAS,CAAC,gBAAgB,GAAG,SAAS,CAAC,EAAE,CAAC;gBAGpD,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,MAAM;IAUhC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO;CAIzC;AAED;;GAEG;AACH,cAAM,WAAW;aAUC,KAAK,EAAE,SAAS;aAChB,cAAc,EAAE,MAAM;aACtB,MAAM,EAAE,MAAM;aACd,GAAG,EAAE,QAAQ;aACb,kBAAkB,EAAE,MAAM,GAAG,SAAS;IAbvD;;;;;;;OAOG;gBAEc,KAAK,EAAE,SAAS,EAChB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,QAAQ,EACb,kBAAkB,EAAE,MAAM,GAAG,SAAS;CAEvD;AAED;;GAEG;AACH,cAAM,gBAAiB,YAAW,MAAM;aAWtB,MAAM,EAAE,gBAAgB,GAAG,SAAS;aACpC,WAAW,EAAE,QAAQ;aACrB,WAAW,EAAE,MAAM;aACnB,kBAAkB,EAAE,MAAM,GAAG,SAAS;aACtC,qBAAqB,EAAE,MAAM,GAAG,SAAS;aACzC,KAAK,EAAE,SAAS;aAChB,cAAc,EAAE,MAAM;aACtB,WAAW,EAAE,MAAM;IAjBpC;;;;;;;;OAQG;gBAEc,MAAM,EAAE,gBAAgB,GAAG,SAAS,EAAE,gDAAgD;IACtF,WAAW,EAAE,QAAQ,EACrB,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,qBAAqB,EAAE,MAAM,GAAG,SAAS,EACzC,KAAK,EAAE,SAAS,EAAE,+EAA+E;IACjG,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM;CAEpC;AAED;;;;GAIG;AACH,cAAM,MAAO,SAAQ,iBAAkB,YAAW,aAAa;IAmB3C,OAAO,CAAC,QAAQ,CAAC,KAAK;IAlBzC,OAAO,CAAC,aAAa,CAAU;IAE/B,OAAO,CAAC,gBAAgB,CAA+B;IAGvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IAE/D,IAAI,EAAE,kBAAkB,CAA6B;IAG5D,OAAO,CAAC,QAAQ,CAAC,CAAW;IAI5B,OAAO,CAAC,YAAY,CAAa;gBAGG,KAAK,EAAE,YAAY;IAQvD,IAAW,CAAC,WAAW,CAAC,IAAI,YAAY,GAAG,SAAS,CAEnD;IAEM,WAAW,IAAI,OAAO;IAWtB,IAAI,IAAI,MAAM;IASrB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAStB;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ;IAST,SAAS,IAAI,OAAO;IAYpB,SAAS,IAAI,IAAI;IAOjB,WAAW,IAAI,QAAQ;IAIvB,cAAc,IAAI,MAAM;IAexB,SAAS,IAAI,OAAO;IAepB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAkB1C;;;OAGG;IACH,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,kBAAkB;IAQnB,YAAY,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,WAAW;IAOlD,OAAO,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS;IAI3D,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED,SAAgB,UAAU,EAAE,MAAM,CAAK;IAEvC,IAAW,WAAW,IAAI,MAAM,CAE/B;IAEM,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAWlC,QAAQ,IAAI,OAAO;IAanB,QAAQ,IAAI,IAAI;IAahB,UAAU,IAAI,OAAO;IAYrB,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAWtC,IAAW,IAAI,IAAI,wBAAwB,CAE1C;IAED,IAAW,KAAK,IAAI,KAAK,CAgBxB;CACD"}
+{"version":3,"file":"uniformChunk.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/uniformChunk.ts"],"names":[],"mappings":"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"}

package/dist/feature-libraries/chunked-forest/uniformChunk.js

@@ -153,9 +153,10 @@ function clonePositions(indexOfParentInOutput, [key, shape, copies], indexOfPare
 /**
  * The shape (see `TreeShape`) of a sequence of trees, all with the same shape (like `FieldShape`, but without a field key).
  *
- * This shape is optimized (by caching derived data like the positions array),
- * so that when paired with a value array it can be efficiently traversed like a tree by an {@link ITreeCursorSynchronous}.
- * See {@link uniformChunk} for how to do this.
+ * @remarks
+ * Paired with a value array, this lets a {@link UniformChunk} be traversed like a tree by an
+ * {@link ITreeCursorSynchronous}. The {@link Cursor} derives each node's position info from the
+ * shared {@link TreeShape.positions} plus the node's top-level index.
  *
  * TODO: consider storing shape information in WASM
  */
@@ -164,10 +165,6 @@ class ChunkShape {
         this.treeShape = treeShape;
         this.topLevelLength = topLevelLength;
         (0, internal_1.assert)(topLevelLength > 0, 0x4c6 /* topLevelLength must be greater than 0 */);
-        // TODO: avoid duplication from inner loop
-        const positions = [undefined];
-        clonePositions(0, [index_js_1.dummyRoot, treeShape, topLevelLength], 0, 0, positions);
-        this.positions = positions;
     }
     equals(other) {
         // TODO: either dedup instances and/or store a collision resistant hash for fast compare.
@@ -196,17 +193,19 @@ class OffsetShape {
     }
 }
 /**
- * Information about a node at a specific position within a uniform chunk.
+ * Information about a node at a specific position within one top-level tree of a {@link TreeShape}.
  */
 class NodePositionInfo {
     /**
-     * @param parent - TODO
-     * @param parentField - TODO
+     * @param parent - The parent node's {@link NodePositionInfo} or `undefined` for a root.
+     * @param parentField - The {@link FieldKey} of the field this node occupies within its parent.
      * @param parentIndex - indexWithinParentField
-     * @param indexOfParentField - which field of the parent `parentIndex` is indexing into to locate this.
-     * @param indexOfParentPosition - Index of parent NodePositionInfo in positions array. TODO: use offsets to avoid copying at top level?
+     * @param indexOfParentField - Which field of the parent `parentIndex` is indexing into to locate this.
+     * @param indexOfParentPosition - Index of this node's parent in {@link TreeShape.positions}
      * @param shape - Shape of the top level sequence this node is part of
-     * @param valueOffset - TODO
+     * @param topLevelLength - Number of siblings in this node's field. For a root this is unused
+     * @param valueOffset - Offset of this node's value within one top-level tree's slice of the chunk's flat `values` array;
+     * only valid when `shape.hasValue` (otherwise it's where the value would have gone, and should not be used to read a value).
      */
     constructor(parent, // TODO; general UpPath to allow prefixing here?
     parentField, parentIndex, indexOfParentField, indexOfParentPosition, shape, // Shape of sequence that contains this node (top level is parent of this node)
@@ -224,20 +223,26 @@ class NodePositionInfo {
 /**
  * The cursor implementation for `UniformChunk`.
  *
- * Works by tracking its location in the chunk's `positions` array.
+ * @remarks
+ * Tracks a flat `positionIndex` and derives each node's position info from the shape's shared
+ * {@link TreeShape.positions} plus the node's top-level index.
  */
 class Cursor extends treeCursorUtils_js_1.SynchronousCursor {
     // TODO: support prefix (path above root, including index offset of chunk in its containing field)
     constructor(chunk) {
         super();
         this.chunk = chunk;
+        /** Which top-level node of the chunk the current position is within. Valid when nodePositionInfo !== undefined. */
+        this.topLevelIndex = 0;
         this.mode = 1 /* CursorLocationType.Fields */;
         // Valid only in fields mode. Can be past end for empty fields.
         // This is redundant with fieldKey above (but might be worth keeping for perf), and could be removed.
         this.indexOfField = 0;
         this.chunkStart = 0;
         this.shape = this.chunk.shape;
-        this.positions = this.shape.positions;
+        this.treeShape = this.shape.treeShape;
+        this.nodeLength = this.treeShape.positions.length;
+        this.stride = this.treeShape.valuesPerTopLevelNode;
         this.fieldKey = index_js_1.dummyRoot;
         this.moveToPosition(0);
     }
@@ -259,18 +264,62 @@ class Cursor extends treeCursorUtils_js_1.SynchronousCursor {
     }
     /**
      * Change the current node within the chunk.
+     *
+     * @param positionIndex - flat position index of the newly selected node. This is NOT an index
+     * within a field, and is not bounds checked.
+     *
+     * @remarks
+     * Decomposes the index into {@link Cursor.topLevelIndex} and {@link Cursor.nodePositionInfo}.
      * See `nodeInfo` for getting data about the current node.
      *
-     * @param positionIndex - index of the position of the newly selected node in `positions`.
-     * This is NOT an index within a field, and is not bounds checked.
      */
     moveToPosition(positionIndex) {
-        this.nodePositionInfo = this.positions[positionIndex];
         this.positionIndex = positionIndex;
-        if (this.nodePositionInfo === undefined) {
-            (0, internal_1.assert)(positionIndex === 0, 0x561 /* expected root at start */);
+        if (positionIndex === 0) {
+            this.nodePositionInfo = undefined;
             (0, internal_1.assert)(this.mode === 1 /* CursorLocationType.Fields */, 0x562 /* expected root to be a field */);
+            return;
         }
+        const decoded = this.decodePosition(positionIndex);
+        this.topLevelIndex = decoded.topLevelIndex;
+        this.nodePositionInfo = decoded.info;
+    }
+    /**
+     * Decode a flat `positionIndex` into its components.
+     *
+     * @param positionIndex - flat position index of the node to decode. Must be greater than 0;
+     * @returns the node's index within {@link TreeShape.positions} (`withinTree`), which top-level
+     * tree holds it (`topLevelIndex`), and the corresponding shared {@link NodePositionInfo} (`info`).
+     */
+    decodePosition(positionIndex) {
+        const offset = positionIndex - 1;
+        // Find the node's index within treeShape.positions, then which top-level tree holds it.
+        const withinTree = offset % this.nodeLength; // remainder
+        const topLevelIndex = (offset - withinTree) / this.nodeLength; // quotient
+        const info = this.treeShape.positions[withinTree] ?? (0, internal_1.oob)();
+        return { withinTree, topLevelIndex, info };
+    }
+    /**
+     * Build a standalone {@link UpPath} for the node at `positionIndex`. O(depth) allocation.
+     *
+     * @remarks
+     * walks the shared per-tree {@link TreeShape.positions} and applies the top-level index
+     * at each level. Mirrors how the `BasicChunk` cursor allocates paths.
+     */
+    materializePath(positionIndex) {
+        if (positionIndex === 0) {
+            return undefined;
+        }
+        const { withinTree, topLevelIndex, info } = this.decodePosition(positionIndex);
+        if (info.parent === undefined) {
+            // Top-level node: its parent is the (prefixed) chunk root.
+            return { parent: undefined, parentField: info.parentField, parentIndex: topLevelIndex };
+        }
+        return {
+            parent: this.materializePath(positionIndex - withinTree + (info.indexOfParentPosition ?? (0, internal_1.oob)())),
+            parentField: info.parentField,
+            parentIndex: info.parentIndex,
+        };
     }
     /**
      * Gets information about the current node.
@@ -364,29 +413,43 @@ class Cursor extends treeCursorUtils_js_1.SynchronousCursor {
     enterRootNodeInner(childIndex) {
         this.mode = 0 /* CursorLocationType.Nodes */;
         this.fieldKey = undefined;
-        // 1 for the "undefined" at the beginning of the positions array, then stride by top level tree shape.
-        this.moveToPosition(1 + childIndex * this.shape.treeShape.positions.length);
+        // 1 for the "undefined" root-field marker at position 0, then stride by one top-level tree (nodeLength).
+        this.moveToPosition(1 + childIndex * this.nodeLength);
         (0, internal_1.assert)(this.fieldIndex === childIndex, 0x543 /* should be at selected child */);
     }
     getFieldPath(prefix) {
         return (0, treeCursorUtils_js_1.prefixFieldPath)(prefix, {
             field: this.getFieldKey(),
-            parent: this.nodePositionInfo,
+            parent: this.materializePath(this.positionIndex),
         });
     }
     getPath(prefix) {
-        return (0, treeCursorUtils_js_1.prefixPath)(prefix, this.nodeInfo(0 /* CursorLocationType.Nodes */));
+        this.nodeInfo(0 /* CursorLocationType.Nodes */); // assert: in nodes mode at a node
+        return (0, treeCursorUtils_js_1.prefixPath)(prefix, this.materializePath(this.positionIndex));
     }
     get fieldIndex() {
-        return this.nodeInfo(0 /* CursorLocationType.Nodes */).parentIndex;
+        const info = this.nodeInfo(0 /* CursorLocationType.Nodes */);
+        return info.parent === undefined ? this.topLevelIndex : info.parentIndex;
+    }
+    /**
+     * Number of nodes in `info`'s field including `info` itself.
+     *
+     * @remarks
+     * For top-level nodes this is the chunk's `topLevelLength`, read from the chunk
+     * rather than the node, so the shared per-tree {@link TreeShape.positions} stays independent of
+     * chunk length; the root entry's own `topLevelLength` field is unused. Nested nodes use the
+     * field length stored on the node.
+     */
+    siblingCount(info) {
+        return info.parent === undefined ? this.shape.topLevelLength : info.topLevelLength;
     }
     get chunkLength() {
-        return this.nodeInfo(0 /* CursorLocationType.Nodes */).topLevelLength;
+        return this.siblingCount(this.nodeInfo(0 /* CursorLocationType.Nodes */));
     }
     seekNodes(offset) {
         const info = this.nodeInfo(0 /* CursorLocationType.Nodes */);
-        const index = offset + info.parentIndex;
-        if (index >= 0 && index < info.topLevelLength) {
+        const index = offset + this.fieldIndex;
+        if (index >= 0 && index < this.siblingCount(info)) {
             this.moveToPosition(this.positionIndex + offset * info.shape.positions.length);
             return true;
         }
@@ -396,8 +459,8 @@ class Cursor extends treeCursorUtils_js_1.SynchronousCursor {
     nextNode() {
         // This is the same as `return this.seekNodes(1);` but slightly faster.
         const info = this.nodeInfo(0 /* CursorLocationType.Nodes */);
-        const index = info.parentIndex + 1;
-        if (index === info.topLevelLength) {
+        const index = this.fieldIndex + 1;
+        if (index === this.siblingCount(info)) {
             this.exitNode();
             return false;
         }
@@ -406,13 +469,15 @@ class Cursor extends treeCursorUtils_js_1.SynchronousCursor {
     }
     exitNode() {
         const info = this.nodeInfo(0 /* CursorLocationType.Nodes */);
-        this.indexOfField =
-            info.indexOfParentField ??
-                (0, internal_1.fail)(0xb0a /* navigation up to root field not yet supported */); // TODO;
+        const withinTree = this.positionIndex - 1 - this.topLevelIndex * this.nodeLength;
+        // Top-level nodes (no parent) exit to the root field at position 0;
+        // nested nodes' parent is `indexOfParentPosition` within the same top-level instance.
+        this.indexOfField = info.indexOfParentField ?? 0;
         this.fieldKey = info.parentField;
         this.mode = 1 /* CursorLocationType.Fields */;
-        this.moveToPosition(info.indexOfParentPosition ??
-            (0, internal_1.fail)(0xb0b /* navigation up to root field not yet supported */)); // TODO
+        this.moveToPosition(info.indexOfParentPosition === undefined
+            ? 0
+            : this.positionIndex - withinTree + info.indexOfParentPosition);
     }
     firstField() {
         const fieldsArray = this.nodeInfo(0 /* CursorLocationType.Nodes */).shape.fieldsArray;
@@ -441,7 +506,7 @@ class Cursor extends treeCursorUtils_js_1.SynchronousCursor {
     get value() {
         const info = this.nodeInfo(0 /* CursorLocationType.Nodes */);
         if (info.shape.hasValue) {
-            const value = this.chunk.values[info.valueOffset];
+            const value = this.chunk.values[info.valueOffset + this.topLevelIndex * this.stride];
             // If mayContainCompressedIds is set, check if the value is a number (i.e. a compressed ID that needs decompression).
             if (info.shape.mayContainCompressedIds && typeof value === "number") {
                 const idCompressor = this.chunk.idCompressor;