@fluidframework/tree 2.102.0 → 2.110.0

package/lib/feature-libraries/chunked-forest/codec/format/formatVText.d.ts

@@ -2,7 +2,8 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { type Static } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
+import type { Static } from "@sinclair/typebox";
 /**
  * A node shape that derives from another node shape by overlaying property-level overrides.
  *
@@ -27,14 +28,14 @@ import { type Static } from "@sinclair/typebox";
  * Decoded by {@link applySpecialization}.
  */
 export type EncodedSpecializedNodeShape = Static<typeof EncodedSpecializedNodeShape>;
-export declare const EncodedSpecializedNodeShape: import("@sinclair/typebox").TObject<{
+export declare const EncodedSpecializedNodeShape: Type.TObject<{
     /**
      * Index into the enclosing batch's shapes array of the shape this specializes.
      * Must resolve to either an {@link EncodedNodeShape} or another
      * `EncodedSpecializedNodeShape`; chains are followed transitively until a node shape
      * is reached. This restriction is enforced at runtime, not by the schema.
      */
-    base: import("@sinclair/typebox").TNumber;
+    base: Type.TNumber;
     /**
      * Field-level overrides applied to the resolved base's `fields`. Entries whose key
      * matches a base field replace that field's shape index in place; entries with new
@@ -42,17 +43,17 @@ export declare const EncodedSpecializedNodeShape: import("@sinclair/typebox").TO
      * is preserved — this is the stream consumption order at decode time, so encoders
      * must serialize per-field tokens in the resulting field order, not in this list's order.
      */
-    fields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TTuple<[import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber]>, import("@sinclair/typebox").TNumber]>>>;
+    fields: Type.TOptional<Type.TArray<Type.TTuple<[Type.TUnion<[Type.TString, Type.TNumber]>, Type.TNumber]>>>;
     /**
      * If absent, inherits the resolved base's value shape. If `null`, the resulting shape
      * has no value shape (explicit clear). Any other value replaces the base's.
      */
-    value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TAny>, import("@sinclair/typebox").TEnum<typeof import("./formatV1.js").SpecialField>]>, import("@sinclair/typebox").TNull]>>;
+    value: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TBoolean, Type.TArray<Type.TAny>, Type.TEnum<typeof import("./formatV1.js").SpecialField>]>, Type.TNull]>>;
     /**
      * If absent, inherits the resolved base's extraFields shape. If `null`, the resulting
      * shape has no extraFields (explicit clear). Any other value replaces the base's.
      */
-    extraFields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TNull]>>;
+    extraFields: Type.TOptional<Type.TUnion<[Type.TNumber, Type.TNull]>>;
 }>;
 /**
  * Experimental extension of {@link EncodedChunkShapeV2}.
@@ -60,15 +61,15 @@ export declare const EncodedSpecializedNodeShape: import("@sinclair/typebox").TO
  * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
  */
 export type EncodedChunkShapeVTextExperimental = Static<typeof EncodedChunkShapeVTextExperimental>;
-export declare const EncodedChunkShapeVTextExperimental: import("@sinclair/typebox").TObject<{
-    f: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+export declare const EncodedChunkShapeVTextExperimental: Type.TObject<{
+    f: Type.TOptional<Type.TObject<{
         /**
          * Index into the enclosing batch's shapes array of the shape this specializes.
          * Must resolve to either an {@link EncodedNodeShape} or another
          * `EncodedSpecializedNodeShape`; chains are followed transitively until a node shape
          * is reached. This restriction is enforced at runtime, not by the schema.
          */
-        base: import("@sinclair/typebox").TNumber;
+        base: Type.TNumber;
         /**
          * Field-level overrides applied to the resolved base's `fields`. Entries whose key
          * matches a base field replace that field's shape index in place; entries with new
@@ -76,30 +77,30 @@ export declare const EncodedChunkShapeVTextExperimental: import("@sinclair/typeb
          * is preserved — this is the stream consumption order at decode time, so encoders
          * must serialize per-field tokens in the resulting field order, not in this list's order.
          */
-        fields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TTuple<[import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber]>, import("@sinclair/typebox").TNumber]>>>;
+        fields: Type.TOptional<Type.TArray<Type.TTuple<[Type.TUnion<[Type.TString, Type.TNumber]>, Type.TNumber]>>>;
         /**
          * If absent, inherits the resolved base's value shape. If `null`, the resulting shape
          * has no value shape (explicit clear). Any other value replaces the base's.
          */
-        value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TAny>, import("@sinclair/typebox").TEnum<typeof import("./formatV1.js").SpecialField>]>, import("@sinclair/typebox").TNull]>>;
+        value: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TBoolean, Type.TArray<Type.TAny>, Type.TEnum<typeof import("./formatV1.js").SpecialField>]>, Type.TNull]>>;
         /**
          * If absent, inherits the resolved base's extraFields shape. If `null`, the resulting
          * shape has no extraFields (explicit clear). Any other value replaces the base's.
          */
-        extraFields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TNull]>>;
+        extraFields: Type.TOptional<Type.TUnion<[Type.TNumber, Type.TNull]>>;
     }>>;
-    e: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TLiteral<0>>;
-    a: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
-    b: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-        length: import("@sinclair/typebox").TNumber;
-        shape: import("@sinclair/typebox").TNumber;
+    e: Type.TOptional<Type.TLiteral<0>>;
+    a: Type.TOptional<Type.TNumber>;
+    b: Type.TOptional<Type.TObject<{
+        length: Type.TNumber;
+        shape: Type.TNumber;
     }>>;
-    c: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-        type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber]>>;
-        value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TAny>, import("@sinclair/typebox").TEnum<typeof import("./formatV1.js").SpecialField>]>>;
-        fields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TTuple<[import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber]>, import("@sinclair/typebox").TNumber]>>>;
-        extraFields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    c: Type.TOptional<Type.TObject<{
+        type: Type.TOptional<Type.TUnion<[Type.TString, Type.TNumber]>>;
+        value: Type.TOptional<Type.TUnion<[Type.TBoolean, Type.TArray<Type.TAny>, Type.TEnum<typeof import("./formatV1.js").SpecialField>]>>;
+        fields: Type.TOptional<Type.TArray<Type.TTuple<[Type.TUnion<[Type.TString, Type.TNumber]>, Type.TNumber]>>>;
+        extraFields: Type.TOptional<Type.TNumber>;
     }>>;
-    d: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TLiteral<0>>;
+    d: Type.TOptional<Type.TLiteral<0>>;
 }>;
 //# sourceMappingURL=formatVText.d.ts.map

package/lib/feature-libraries/chunked-forest/codec/format/formatVText.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatVText.d.ts","sourceRoot":"","sources":["../../../../../src/feature-libraries/chunked-forest/codec/format/formatVText.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AAQtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AACrF,eAAO,MAAM,2BAA2B;IAEtC;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;OAGG;;IAEH;;;OAGG;;EAIJ,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kCAAkC,GAAG,MAAM,CACtD,OAAO,kCAAkC,CACzC,CAAC;AACF,eAAO,MAAM,kCAAkC;;QArC7C;;;;;WAKG;;QAEH;;;;;;WAMG;;QAEH;;;WAGG;;QAEH;;;WAGG;;;;;;;;;;;;;;;;EAoBJ,CAAC"}
+{"version":3,"file":"formatVText.d.ts","sourceRoot":"","sources":["../../../../../src/feature-libraries/chunked-forest/codec/format/formatVText.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAQhD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AACrF,eAAO,MAAM,2BAA2B;IAEtC;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;OAGG;;IAEH;;;OAGG;;EAIJ,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kCAAkC,GAAG,MAAM,CACtD,OAAO,kCAAkC,CACzC,CAAC;AACF,eAAO,MAAM,kCAAkC;;QArC7C;;;;;WAKG;;QAEH;;;;;;WAMG;;QAEH;;;WAGG;;QAEH;;;WAGG;;;;;;;;;;;;;;;;EAoBJ,CAAC"}

package/lib/feature-libraries/chunked-forest/codec/format/formatVText.js

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { Type } from "@sinclair/typebox";
+import * as Type from "@sinclair/typebox";
 import { unionOptions } from "../../../../codec/index.js";
 import { ShapeIndex } from "./formatGeneric.js";
 import { EncodedFieldShape, EncodedValueShape } from "./formatV1.js";

package/lib/feature-libraries/chunked-forest/codec/format/formatVText.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatVText.js","sourceRoot":"","sources":["../../../../../src/feature-libraries/chunked-forest/codec/format/formatVText.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAe,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AA0BzC,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC,MAAM,CACrD;IACC;;;;;OAKG;IACH,IAAI,EAAE,UAAU;IAChB;;;;;;OAMG;IACH,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACpD;;;OAGG;IACH,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,iBAAiB,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAClE;;;OAGG;IACH,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;CACjE,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAC/B,CAAC;AAUF,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,CAAC,MAAM,CAC5D;IACC,GAAG,QAAQ;IACX,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,2BAA2B,CAAC;CAC7C,EACD,YAAY,CACZ,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { type Static, Type } from \"@sinclair/typebox\";\n\nimport { unionOptions } from \"../../../../codec/index.js\";\n\nimport { ShapeIndex } from \"./formatGeneric.js\";\nimport { EncodedFieldShape, EncodedValueShape } from \"./formatV1.js\";\nimport { shapesV2 } from \"./formatV2.js\";\n\n/**\n * A node shape that derives from another node shape by overlaying property-level overrides.\n *\n * @remarks\n * Compresses runs of node shapes that differ only in a few properties: a base node shape\n * defines the structural skeleton, and the specialization narrows specific properties.\n *\n * For example, a base `FormatNode` with a variable-boolean `bold` field can be specialized\n * to a shape that pins `bold` to a constant `true` — every node decoded with the\n * specialization contributes zero stream tokens for `bold`.\n *\n * Specialization rules: `type` is always inherited from the resolved base. `fields` overrides\n * apply per-key: entries whose key matches a base field replace that entry's shape index in\n * place; entries with new keys are appended after all base fields. For `value` and\n * `extraFields`: if the property is absent on the wire, the base's value is inherited; if\n * `null`, the resulting shape has no value / no extraFields (explicit clear); any other value\n * replaces the base's.\n *\n * The `null` sentinel exists because JSON does not preserve `undefined`-valued properties,\n * so override-vs-inherit cannot be discriminated by property presence after persistence.\n *\n * Decoded by {@link applySpecialization}.\n */\nexport type EncodedSpecializedNodeShape = Static<typeof EncodedSpecializedNodeShape>;\nexport const EncodedSpecializedNodeShape = Type.Object(\n\t{\n\t\t/**\n\t\t * Index into the enclosing batch's shapes array of the shape this specializes.\n\t\t * Must resolve to either an {@link EncodedNodeShape} or another\n\t\t * `EncodedSpecializedNodeShape`; chains are followed transitively until a node shape\n\t\t * is reached. This restriction is enforced at runtime, not by the schema.\n\t\t */\n\t\tbase: ShapeIndex,\n\t\t/**\n\t\t * Field-level overrides applied to the resolved base's `fields`. Entries whose key\n\t\t * matches a base field replace that field's shape index in place; entries with new\n\t\t * keys are appended after all base fields, in the order given here. Base field order\n\t\t * is preserved — this is the stream consumption order at decode time, so encoders\n\t\t * must serialize per-field tokens in the resulting field order, not in this list's order.\n\t\t */\n\t\tfields: Type.Optional(Type.Array(EncodedFieldShape)),\n\t\t/**\n\t\t * If absent, inherits the resolved base's value shape. If `null`, the resulting shape\n\t\t * has no value shape (explicit clear). Any other value replaces the base's.\n\t\t */\n\t\tvalue: Type.Optional(Type.Union([EncodedValueShape, Type.Null()])),\n\t\t/**\n\t\t * If absent, inherits the resolved base's extraFields shape. If `null`, the resulting\n\t\t * shape has no extraFields (explicit clear). Any other value replaces the base's.\n\t\t */\n\t\textraFields: Type.Optional(Type.Union([ShapeIndex, Type.Null()])),\n\t},\n\t{ additionalProperties: false },\n);\n\n/**\n * Experimental extension of {@link EncodedChunkShapeV2}.\n * @remarks\n * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.\n */\nexport type EncodedChunkShapeVTextExperimental = Static<\n\ttypeof EncodedChunkShapeVTextExperimental\n>;\nexport const EncodedChunkShapeVTextExperimental = Type.Object(\n\t{\n\t\t...shapesV2,\n\t\tf: Type.Optional(EncodedSpecializedNodeShape),\n\t},\n\tunionOptions,\n);\n"]}
+{"version":3,"file":"formatVText.js","sourceRoot":"","sources":["../../../../../src/feature-libraries/chunked-forest/codec/format/formatVText.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAC;AAG1C,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AA0BzC,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC,MAAM,CACrD;IACC;;;;;OAKG;IACH,IAAI,EAAE,UAAU;IAChB;;;;;;OAMG;IACH,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACpD;;;OAGG;IACH,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,iBAAiB,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAClE;;;OAGG;IACH,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;CACjE,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAC/B,CAAC;AAUF,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,CAAC,MAAM,CAC5D;IACC,GAAG,QAAQ;IACX,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,2BAA2B,CAAC;CAC7C,EACD,YAAY,CACZ,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport * as Type from \"@sinclair/typebox\";\nimport type { Static } from \"@sinclair/typebox\";\n\nimport { unionOptions } from \"../../../../codec/index.js\";\n\nimport { ShapeIndex } from \"./formatGeneric.js\";\nimport { EncodedFieldShape, EncodedValueShape } from \"./formatV1.js\";\nimport { shapesV2 } from \"./formatV2.js\";\n\n/**\n * A node shape that derives from another node shape by overlaying property-level overrides.\n *\n * @remarks\n * Compresses runs of node shapes that differ only in a few properties: a base node shape\n * defines the structural skeleton, and the specialization narrows specific properties.\n *\n * For example, a base `FormatNode` with a variable-boolean `bold` field can be specialized\n * to a shape that pins `bold` to a constant `true` — every node decoded with the\n * specialization contributes zero stream tokens for `bold`.\n *\n * Specialization rules: `type` is always inherited from the resolved base. `fields` overrides\n * apply per-key: entries whose key matches a base field replace that entry's shape index in\n * place; entries with new keys are appended after all base fields. For `value` and\n * `extraFields`: if the property is absent on the wire, the base's value is inherited; if\n * `null`, the resulting shape has no value / no extraFields (explicit clear); any other value\n * replaces the base's.\n *\n * The `null` sentinel exists because JSON does not preserve `undefined`-valued properties,\n * so override-vs-inherit cannot be discriminated by property presence after persistence.\n *\n * Decoded by {@link applySpecialization}.\n */\nexport type EncodedSpecializedNodeShape = Static<typeof EncodedSpecializedNodeShape>;\nexport const EncodedSpecializedNodeShape = Type.Object(\n\t{\n\t\t/**\n\t\t * Index into the enclosing batch's shapes array of the shape this specializes.\n\t\t * Must resolve to either an {@link EncodedNodeShape} or another\n\t\t * `EncodedSpecializedNodeShape`; chains are followed transitively until a node shape\n\t\t * is reached. This restriction is enforced at runtime, not by the schema.\n\t\t */\n\t\tbase: ShapeIndex,\n\t\t/**\n\t\t * Field-level overrides applied to the resolved base's `fields`. Entries whose key\n\t\t * matches a base field replace that field's shape index in place; entries with new\n\t\t * keys are appended after all base fields, in the order given here. Base field order\n\t\t * is preserved — this is the stream consumption order at decode time, so encoders\n\t\t * must serialize per-field tokens in the resulting field order, not in this list's order.\n\t\t */\n\t\tfields: Type.Optional(Type.Array(EncodedFieldShape)),\n\t\t/**\n\t\t * If absent, inherits the resolved base's value shape. If `null`, the resulting shape\n\t\t * has no value shape (explicit clear). Any other value replaces the base's.\n\t\t */\n\t\tvalue: Type.Optional(Type.Union([EncodedValueShape, Type.Null()])),\n\t\t/**\n\t\t * If absent, inherits the resolved base's extraFields shape. If `null`, the resulting\n\t\t * shape has no extraFields (explicit clear). Any other value replaces the base's.\n\t\t */\n\t\textraFields: Type.Optional(Type.Union([ShapeIndex, Type.Null()])),\n\t},\n\t{ additionalProperties: false },\n);\n\n/**\n * Experimental extension of {@link EncodedChunkShapeV2}.\n * @remarks\n * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.\n */\nexport type EncodedChunkShapeVTextExperimental = Static<\n\ttypeof EncodedChunkShapeVTextExperimental\n>;\nexport const EncodedChunkShapeVTextExperimental = Type.Object(\n\t{\n\t\t...shapesV2,\n\t\tf: Type.Optional(EncodedSpecializedNodeShape),\n\t},\n\tunionOptions,\n);\n"]}

package/lib/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/lib/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/lib/feature-libraries/chunked-forest/uniformChunk.js

@@ -147,9 +147,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
  */
@@ -158,10 +159,6 @@ export class ChunkShape {
         this.treeShape = treeShape;
         this.topLevelLength = topLevelLength;
         assert(topLevelLength > 0, 0x4c6 /* topLevelLength must be greater than 0 */);
-        // TODO: avoid duplication from inner loop
-        const positions = [undefined];
-        clonePositions(0, [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.
@@ -189,17 +186,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)
@@ -217,20 +216,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 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 = dummyRoot;
         this.moveToPosition(0);
     }
@@ -252,18 +257,62 @@ class Cursor extends 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) {
-            assert(positionIndex === 0, 0x561 /* expected root at start */);
+        if (positionIndex === 0) {
+            this.nodePositionInfo = undefined;
             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] ?? 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 ?? oob())),
+            parentField: info.parentField,
+            parentIndex: info.parentIndex,
+        };
     }
     /**
      * Gets information about the current node.
@@ -357,29 +406,43 @@ class Cursor extends 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);
         assert(this.fieldIndex === childIndex, 0x543 /* should be at selected child */);
     }
     getFieldPath(prefix) {
         return prefixFieldPath(prefix, {
             field: this.getFieldKey(),
-            parent: this.nodePositionInfo,
+            parent: this.materializePath(this.positionIndex),
         });
     }
     getPath(prefix) {
-        return prefixPath(prefix, this.nodeInfo(0 /* CursorLocationType.Nodes */));
+        this.nodeInfo(0 /* CursorLocationType.Nodes */); // assert: in nodes mode at a node
+        return 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;
         }
@@ -389,8 +452,8 @@ class Cursor extends 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;
         }
@@ -399,13 +462,15 @@ class Cursor extends SynchronousCursor {
     }
     exitNode() {
         const info = this.nodeInfo(0 /* CursorLocationType.Nodes */);
-        this.indexOfField =
-            info.indexOfParentField ??
-                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 ??
-            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;
@@ -434,7 +499,7 @@ class Cursor extends 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;