@loro-extended/change 5.0.0 → 5.2.0

package/README.md

@@ -216,6 +216,100 @@ console.log(doc.toJSON()); // Updated document state
 | Atomic undo/redo                  | Batched: `change(doc, d => { ... })` |
 | Performance-critical bulk updates | Batched: `change(doc, d => { ... })` |
 | Simple reads + writes             | Direct: `doc.users.set(...)`         |
+| Encapsulated ref operations       | Ref-level: `change(ref, d => {...})` |
+
+### Ref-Level `change()` for Encapsulation
+
+The `change()` function also works on individual refs (ListRef, TextRef, TreeRef, etc.), enabling better encapsulation when you want to pass refs around without exposing the entire document:
+
+```typescript
+import { change } from "@loro-extended/change";
+
+// Library code - expose only the ref, not the doc
+class StateMachine {
+  private doc: TypedDoc<...>;
+  
+  get states(): TreeRef<StateNodeShape> {
+    return this.doc.states;
+  }
+}
+
+// User code - works with just the ref
+function addStates(states: TreeRef<StateNodeShape>) {
+  change(states, draft => {
+    const idle = draft.createNode();
+    idle.data.name.insert(0, "idle");
+    
+    const running = draft.createNode();
+    running.data.name.insert(0, "running");
+  });
+}
+
+// Usage
+const machine = new StateMachine();
+addStates(machine.states); // No access to the underlying doc needed!
+```
+
+This pattern is useful for:
+- **Library APIs**: Expose typed refs without leaking document structure
+- **Component isolation**: Pass refs to components that only need partial access
+- **Testing**: Mock or stub individual refs without full document setup
+
+All ref types support `change()`:
+
+```typescript
+// ListRef
+change(doc.items, draft => {
+  draft.push("item1");
+  draft.push("item2");
+});
+
+// TextRef
+change(doc.title, draft => {
+  draft.insert(0, "Hello ");
+  draft.insert(6, "World");
+});
+
+// CounterRef
+change(doc.count, draft => {
+  draft.increment(5);
+  draft.decrement(2);
+});
+
+// StructRef
+change(doc.profile, draft => {
+  draft.bio.insert(0, "Hello");
+  draft.age.increment(1);
+});
+
+// RecordRef
+change(doc.users, draft => {
+  draft.set("alice", { name: "Alice" });
+  draft.set("bob", { name: "Bob" });
+});
+
+// TreeRef
+change(doc.tree, draft => {
+  const node = draft.createNode();
+  node.data.name.insert(0, "root");
+});
+```
+
+Nested `change()` calls are safe - Loro's commit is idempotent:
+
+```typescript
+change(doc.items, outer => {
+  outer.push("from outer");
+  
+  // Nested change on a different ref - works correctly
+  change(doc.count, inner => {
+    inner.increment(10);
+  });
+  
+  outer.push("still in outer");
+});
+// All mutations are committed
+```
 
 ## Advanced Usage
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LoroDoc, Container, LoroTreeNode, TreeID, Subscription, LoroText, LoroList, LoroMovableList, LoroMap, LoroCounter, LoroTree, Value } from 'loro-crdt';
+import { PeerID, LoroDoc, Container, LoroTreeNode, TreeID, Subscription, LoroText, LoroList, LoroMovableList, LoroMap, LoroTree, LoroCounter, Value } from 'loro-crdt';
 
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 /**
@@ -135,6 +135,14 @@ type JsonPatch = JsonPatchOperation[];
  * loro(doc).subscribe(callback);
  * ```
  */
+/**
+ * Frontiers represent a specific version in the document's history.
+ * Each frontier is an operation ID consisting of a peer ID and counter.
+ */
+type Frontiers = {
+    peer: PeerID;
+    counter: number;
+}[];
 type TypedDoc<Shape extends DocShape> = Mutable<Shape> & {
     /**
      * The primary method of mutating typed documents.
@@ -168,6 +176,32 @@ type TypedDoc<Shape extends DocShape> = Mutable<Shape> & {
      * ```
      */
     toJSON(): Infer<Shape>;
+    /**
+     * Creates a new TypedDoc at a specified version (frontiers).
+     * The forked doc will only contain history before the specified frontiers.
+     * The forked doc has a different PeerID from the original.
+     *
+     * For raw LoroDoc access, use: `loro(doc).doc.forkAt(frontiers)`
+     *
+     * @param frontiers - The version to fork at (obtained from `loro(doc).doc.frontiers()`)
+     * @returns A new TypedDoc with the same schema at the specified version
+     *
+     * @example
+     * ```typescript
+     * import { loro } from "@loro-extended/change";
+     *
+     * const doc = createTypedDoc(schema);
+     * doc.title.update("Hello");
+     * const frontiers = loro(doc).doc.frontiers();
+     * doc.title.update("World");
+     *
+     * // Fork at the earlier version
+     * const forkedDoc = doc.forkAt(frontiers);
+     * console.log(forkedDoc.title.toString()); // "Hello"
+     * console.log(doc.title.toString()); // "World"
+     * ```
+     */
+    forkAt(frontiers: Frontiers): TypedDoc<Shape>;
 };
 /**
  * Creates a new TypedDoc with the given schema.
@@ -207,6 +241,133 @@ type TypedDoc<Shape extends DocShape> = Mutable<Shape> & {
  */
 declare function createTypedDoc<Shape extends DocShape>(shape: Shape, existingDoc?: LoroDoc): TypedDoc<Shape>;
 
+/**
+ * Symbol for internal methods that should not be enumerable or accessible to users.
+ * Used to hide implementation details like absorbPlainValues(), getTypedRefParams(), etc.
+ *
+ * This achieves Success Criteria #7 from loro-api-refactor.md:
+ * "Internal methods hidden - Via Symbol, not enumerable"
+ */
+declare const INTERNAL_SYMBOL: unique symbol;
+/**
+ * Minimal interface for refs that only need absorbPlainValues.
+ * Used by TreeNodeRef which doesn't extend TypedRef.
+ */
+interface RefInternalsBase {
+    /** Absorb mutated plain values back into Loro containers */
+    absorbPlainValues(): void;
+}
+type TypedRefParams<Shape extends DocShape | ContainerShape> = {
+    shape: Shape;
+    placeholder?: Infer<Shape>;
+    getContainer: () => ShapeToContainer<Shape>;
+    autoCommit?: boolean;
+    batchedMutation?: boolean;
+    getDoc: () => LoroDoc;
+};
+/**
+ * Abstract base class for all ref internal implementations.
+ * Contains shared logic that was previously in TypedRef.createBaseInternals().
+ *
+ * Subclasses implement specific behavior for each ref type.
+ */
+declare abstract class BaseRefInternals<Shape extends DocShape | ContainerShape> implements RefInternalsBase {
+    protected readonly params: TypedRefParams<Shape>;
+    protected cachedContainer: ShapeToContainer<Shape> | undefined;
+    protected loroNamespace: LoroRefBase | undefined;
+    constructor(params: TypedRefParams<Shape>);
+    /** Get the underlying Loro container (cached) */
+    getContainer(): ShapeToContainer<Shape>;
+    /** Commit changes if autoCommit is enabled */
+    commitIfAuto(): void;
+    /** Get the shape for this ref */
+    getShape(): Shape;
+    /** Get the placeholder value */
+    getPlaceholder(): Infer<Shape> | undefined;
+    /** Check if autoCommit is enabled */
+    getAutoCommit(): boolean;
+    /** Check if in batched mutation mode */
+    getBatchedMutation(): boolean;
+    /** Get the LoroDoc */
+    getDoc(): LoroDoc;
+    /**
+     * Get the TypedRefParams needed to recreate this ref.
+     * Used by change() to create draft refs with modified params.
+     *
+     * Returns a new params object with the same shape, placeholder, getContainer, and getDoc,
+     * but allows overriding autoCommit and batchedMutation for draft creation.
+     */
+    getTypedRefParams(): TypedRefParams<Shape>;
+    /** Get the loro namespace (cached) */
+    getLoroNamespace(): LoroRefBase;
+    /** Absorb mutated plain values back into Loro containers - subclasses override */
+    abstract absorbPlainValues(): void;
+    /** Create the loro() namespace object - subclasses override for specific types */
+    protected createLoroNamespace(): LoroRefBase;
+}
+/**
+ * Base class for all typed refs.
+ *
+ * All internal methods are accessed via [INTERNAL_SYMBOL] to prevent
+ * namespace collisions with user data properties.
+ *
+ * Uses the Facade + Implementation pattern:
+ * - TypedRef is the thin public facade
+ * - BaseRefInternals subclasses contain all implementation logic
+ */
+declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
+    /**
+     * Internal implementation accessed via Symbol.
+     * Subclasses must set this to their specific internals class instance.
+     */
+    abstract [INTERNAL_SYMBOL]: BaseRefInternals<Shape>;
+    /**
+     * Serializes the ref to a plain JSON-compatible value.
+     * Returns the plain type inferred from the shape.
+     */
+    abstract toJSON(): Infer<Shape>;
+    /**
+     * Access the loro() namespace via the well-known symbol.
+     * This is used by the loro() function to access CRDT internals.
+     */
+    get [LORO_SYMBOL](): LoroRefBase;
+}
+
+/**
+ * Internal implementation for CounterRef.
+ * Contains all logic, state, and implementation details.
+ */
+declare class CounterRefInternals extends BaseRefInternals<CounterContainerShape> {
+    private materialized;
+    /** Increment the counter value */
+    increment(value?: number): void;
+    /** Decrement the counter value */
+    decrement(value?: number): void;
+    /** Get the current counter value */
+    getValue(): number;
+    /** No plain values in counter */
+    absorbPlainValues(): void;
+    /** Create the loro namespace for counter */
+    protected createLoroNamespace(): LoroCounterRef;
+}
+
+/**
+ * Counter typed ref - thin facade that delegates to CounterRefInternals.
+ */
+declare class CounterRef extends TypedRef<CounterContainerShape> {
+    [INTERNAL_SYMBOL]: CounterRefInternals;
+    constructor(params: TypedRefParams<CounterContainerShape>);
+    /** Increment the counter by the given value (default 1) */
+    increment(value?: number): void;
+    /** Decrement the counter by the given value (default 1) */
+    decrement(value?: number): void;
+    /** Get the current counter value */
+    get value(): number;
+    valueOf(): number;
+    toJSON(): number;
+    [Symbol.toPrimitive](hint: string): number | string;
+}
+
 /**
  * Internal implementation for ListRefBase.
  * Contains all logic, state, and implementation details for list operations.
@@ -214,7 +375,7 @@ declare function createTypedDoc<Shape extends DocShape>(shape: Shape, existingDo
 declare class ListRefBaseInternals<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"], MutableItem = NestedShape["_mutable"]> extends BaseRefInternals<any> {
     private itemCache;
     /** Get typed ref params for creating child refs at an index */
-    getTypedRefParams(index: number, shape: ContainerShape): TypedRefParams<ContainerShape>;
+    getChildTypedRefParams(index: number, shape: ContainerShape): TypedRefParams<ContainerShape>;
     /** Get item for predicate functions (returns plain value) */
     getPredicateItem(index: number): Item | undefined;
     /** Get mutable item for return values (returns ref or cached value) */
@@ -310,7 +471,7 @@ declare class MovableListRef<NestedShape extends ContainerOrValueShape, Item = N
 declare class RecordRefInternals<NestedShape extends ContainerOrValueShape> extends BaseRefInternals<any> {
     private refCache;
     /** Get typed ref params for creating child refs at a key */
-    getTypedRefParams(key: string, shape: ContainerShape): TypedRefParams<ContainerShape>;
+    getChildTypedRefParams(key: string, shape: ContainerShape): TypedRefParams<ContainerShape>;
     /** Get a ref for a key without creating (returns undefined for non-existent container keys) */
     getRef(key: string): unknown;
     /** Get or create a ref for a key (always creates for container shapes) */
@@ -398,6 +559,11 @@ type StructRef<NestedShapes extends Record<string, ContainerOrValueShape>> = {
      * @internal
      */
     [INTERNAL_SYMBOL]: RefInternalsBase;
+    /**
+     * Access CRDT internals via the well-known symbol.
+     * Used by the loro() function.
+     */
+    [LORO_SYMBOL]: LoroMapRef;
 };
 
 /**
@@ -481,6 +647,7 @@ interface TreeRefLike<DataShape extends StructContainerShape> {
 declare class TreeNodeRefInternals<DataShape extends StructContainerShape> implements RefInternalsBase {
     private readonly params;
     private dataRef;
+    private loroNamespace;
     constructor(params: TreeNodeRefParams<DataShape>);
     /** Get the underlying LoroTreeNode */
     getNode(): LoroTreeNode;
@@ -500,6 +667,10 @@ declare class TreeNodeRefInternals<DataShape extends StructContainerShape> imple
     getOrCreateDataRef(): StructRef<DataShape["shapes"]>;
     /** Absorb mutated plain values back into Loro containers */
     absorbPlainValues(): void;
+    /** Get the loro namespace (cached) */
+    getLoroNamespace(): LoroTreeNodeRef;
+    /** Create the loro namespace for tree node */
+    protected createLoroNamespace(): LoroTreeNodeRef;
 }
 
 interface TreeNodeRefParams<DataShape extends StructContainerShape> {
@@ -529,6 +700,10 @@ interface TreeNodeRefParams<DataShape extends StructContainerShape> {
 declare class TreeNodeRef<DataShape extends StructContainerShape> {
     [INTERNAL_SYMBOL]: TreeNodeRefInternals<DataShape>;
     constructor(params: TreeNodeRefParams<DataShape>);
+    /**
+     * Access the loro() namespace via the well-known symbol.
+     */
+    get [LORO_SYMBOL](): LoroTreeNodeRef;
     /**
      * The unique TreeID of this node.
      */
@@ -675,9 +850,14 @@ declare class TreeRef<DataShape extends StructContainerShape> extends TypedRef<T
     roots(): TreeNodeRef<DataShape>[];
     /**
      * Get all nodes in the tree (unordered).
-     * Includes all nodes, not just roots.
+     * By default, excludes deleted nodes (tombstones).
+     *
+     * @param options.includeDeleted - If true, includes deleted nodes. Default: false.
+     * @returns Array of TreeNodeRef for matching nodes
      */
-    nodes(): TreeNodeRef<DataShape>[];
+    nodes(options?: {
+        includeDeleted?: boolean;
+    }): TreeNodeRef<DataShape>[];
     /**
      * Check if a node with the given ID exists in the tree.
      */
@@ -804,6 +984,13 @@ interface LoroTreeRef extends LoroRefBase {
     /** The underlying LoroTree */
     readonly container: LoroTree;
 }
+/**
+ * loro() return type for TreeNodeRef.
+ */
+interface LoroTreeNodeRef extends LoroRefBase {
+    /** The underlying LoroTreeNode */
+    readonly container: LoroTreeNode;
+}
 /**
  * loro() return type for TypedDoc.
  * Provides access to doc-level operations.
@@ -849,7 +1036,11 @@ declare function loro(ref: CounterRef): LoroCounterRef;
 /**
  * Access CRDT internals for a TreeRef.
  */
-declare function loro<DataShape extends StructContainerShape>(ref: TreeRef<DataShape>): LoroTreeRef;
+declare function loro<DataShape extends StructContainerShape>(ref: TreeRef<DataShape> | TreeRefInterface<DataShape>): LoroTreeRef;
+/**
+ * Access CRDT internals for a TreeNodeRef.
+ */
+declare function loro<DataShape extends StructContainerShape>(ref: TreeNodeRef<DataShape>): LoroTreeNodeRef;
 /**
  * Access CRDT internals for a TypedDoc.
  */
@@ -859,125 +1050,6 @@ declare function loro<Shape extends DocShape>(doc: TypedDoc<Shape>): LoroTypedDo
  */
 declare function loro<Shape extends ContainerShape>(ref: TypedRef<Shape>): LoroRefBase;
 
-/**
- * Symbol for internal methods that should not be enumerable or accessible to users.
- * Used to hide implementation details like absorbPlainValues(), getTypedRefParams(), etc.
- *
- * This achieves Success Criteria #7 from loro-api-refactor.md:
- * "Internal methods hidden - Via Symbol, not enumerable"
- */
-declare const INTERNAL_SYMBOL: unique symbol;
-/**
- * Minimal interface for refs that only need absorbPlainValues.
- * Used by TreeNodeRef which doesn't extend TypedRef.
- */
-interface RefInternalsBase {
-    /** Absorb mutated plain values back into Loro containers */
-    absorbPlainValues(): void;
-}
-type TypedRefParams<Shape extends DocShape | ContainerShape> = {
-    shape: Shape;
-    placeholder?: Infer<Shape>;
-    getContainer: () => ShapeToContainer<Shape>;
-    autoCommit?: boolean;
-    batchedMutation?: boolean;
-    getDoc: () => LoroDoc;
-};
-/**
- * Abstract base class for all ref internal implementations.
- * Contains shared logic that was previously in TypedRef.createBaseInternals().
- *
- * Subclasses implement specific behavior for each ref type.
- */
-declare abstract class BaseRefInternals<Shape extends DocShape | ContainerShape> implements RefInternalsBase {
-    protected readonly params: TypedRefParams<Shape>;
-    protected cachedContainer: ShapeToContainer<Shape> | undefined;
-    protected loroNamespace: LoroRefBase | undefined;
-    constructor(params: TypedRefParams<Shape>);
-    /** Get the underlying Loro container (cached) */
-    getContainer(): ShapeToContainer<Shape>;
-    /** Commit changes if autoCommit is enabled */
-    commitIfAuto(): void;
-    /** Get the shape for this ref */
-    getShape(): Shape;
-    /** Get the placeholder value */
-    getPlaceholder(): Infer<Shape> | undefined;
-    /** Check if autoCommit is enabled */
-    getAutoCommit(): boolean;
-    /** Check if in batched mutation mode */
-    getBatchedMutation(): boolean;
-    /** Get the LoroDoc */
-    getDoc(): LoroDoc;
-    /** Get the loro namespace (cached) */
-    getLoroNamespace(): LoroRefBase;
-    /** Absorb mutated plain values back into Loro containers - subclasses override */
-    abstract absorbPlainValues(): void;
-    /** Create the loro() namespace object - subclasses override for specific types */
-    protected createLoroNamespace(): LoroRefBase;
-}
-/**
- * Base class for all typed refs.
- *
- * All internal methods are accessed via [INTERNAL_SYMBOL] to prevent
- * namespace collisions with user data properties.
- *
- * Uses the Facade + Implementation pattern:
- * - TypedRef is the thin public facade
- * - BaseRefInternals subclasses contain all implementation logic
- */
-declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
-    /**
-     * Internal implementation accessed via Symbol.
-     * Subclasses must set this to their specific internals class instance.
-     */
-    abstract [INTERNAL_SYMBOL]: BaseRefInternals<Shape>;
-    /**
-     * Serializes the ref to a plain JSON-compatible value.
-     * Returns the plain type inferred from the shape.
-     */
-    abstract toJSON(): Infer<Shape>;
-    /**
-     * Access the loro() namespace via the well-known symbol.
-     * This is used by the loro() function to access CRDT internals.
-     */
-    get [LORO_SYMBOL](): LoroRefBase;
-}
-
-/**
- * Internal implementation for CounterRef.
- * Contains all logic, state, and implementation details.
- */
-declare class CounterRefInternals extends BaseRefInternals<CounterContainerShape> {
-    private materialized;
-    /** Increment the counter value */
-    increment(value?: number): void;
-    /** Decrement the counter value */
-    decrement(value?: number): void;
-    /** Get the current counter value */
-    getValue(): number;
-    /** No plain values in counter */
-    absorbPlainValues(): void;
-    /** Create the loro namespace for counter */
-    protected createLoroNamespace(): LoroCounterRef;
-}
-
-/**
- * Counter typed ref - thin facade that delegates to CounterRefInternals.
- */
-declare class CounterRef extends TypedRef<CounterContainerShape> {
-    [INTERNAL_SYMBOL]: CounterRefInternals;
-    constructor(params: TypedRefParams<CounterContainerShape>);
-    /** Increment the counter by the given value (default 1) */
-    increment(value?: number): void;
-    /** Decrement the counter by the given value (default 1) */
-    decrement(value?: number): void;
-    /** Get the current counter value */
-    get value(): number;
-    valueOf(): number;
-    toJSON(): number;
-    [Symbol.toPrimitive](hint: string): number | string;
-}
-
 type WithPlaceholder<S extends Shape<any, any, any>> = S & {
     placeholder(value: S["_placeholder"]): S;
 };
@@ -1034,8 +1106,10 @@ interface TreeRefInterface<DataShape extends StructContainerShape> {
     createNode(initialData?: Partial<DataShape["_plain"]>): TreeNodeRef<DataShape>;
     /** Get all root nodes (nodes without parents) */
     roots(): TreeNodeRef<DataShape>[];
-    /** Get all nodes in the tree (unordered) */
-    nodes(): TreeNodeRef<DataShape>[];
+    /** Get all nodes in the tree (unordered). By default excludes deleted nodes. */
+    nodes(options?: {
+        includeDeleted?: boolean;
+    }): TreeNodeRef<DataShape>[];
     /** Check if a node with the given ID exists in the tree */
     has(id: TreeID): boolean;
     /** Enable fractional index generation for ordering */
@@ -1048,6 +1122,10 @@ interface TreeRefInterface<DataShape extends StructContainerShape> {
         fractionalIndex: string;
         data: DataShape["_plain"];
     }>;
+    /**
+     * Access CRDT internals via the well-known symbol.
+     */
+    readonly [LORO_SYMBOL]: LoroTreeRef;
 }
 /**
  * Container shape for tree (forest) structures.
@@ -1092,9 +1170,7 @@ type MapContainerShape<NestedShapes extends Record<string, ContainerOrValueShape
  */
 interface StructContainerShape<NestedShapes extends Record<string, ContainerOrValueShape> = Record<string, ContainerOrValueShape>> extends Shape<{
     [K in keyof NestedShapes]: NestedShapes[K]["_plain"];
-}, StructRef<NestedShapes> & {
-    [K in keyof NestedShapes]: NestedShapes[K]["_mutable"];
-}, {
+}, StructRef<NestedShapes>, {
     [K in keyof NestedShapes]: NestedShapes[K]["_placeholder"];
 }> {
     readonly _type: "struct";
@@ -1394,7 +1470,7 @@ declare function derivePlaceholder<T extends DocShape>(schema: T): InferPlacehol
 declare function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown;
 
 /**
- * The primary method of mutating typed documents.
+ * The primary method of mutating typed documents and refs.
  * Batches multiple mutations into a single transaction.
  * All changes commit together at the end.
  *
@@ -1403,26 +1479,46 @@ declare function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown;
  * - Performance (fewer commits)
  * - Atomic undo (all changes = one undo step)
  *
- * Returns the doc for chaining.
+ * Returns the doc/ref for chaining.
  *
- * @param doc - The TypedDoc to mutate
+ * @param target - The TypedDoc or TypedRef to mutate
  * @param fn - Function that performs mutations on the draft
- * @returns The same TypedDoc for chaining
+ * @returns The same target for chaining
  *
  * @example
  * ```typescript
  * import { change } from "@loro-extended/change"
  *
- * // Chainable API
+ * // Document-level change (chainable)
  * change(doc, draft => {
  *   draft.count.increment(10)
  *   draft.title.update("Hello")
  * })
  *   .count.increment(5)  // Optional: continue mutating
- *   .toJSON()            // Optional: get last item snapshot when needed
+ *   .toJSON()            // Optional: get snapshot
+ *
+ * // Ref-level change - enables encapsulation
+ * function addItems(list: ListRef<...>) {
+ *   change(list, draft => {
+ *     draft.push({ name: "item1" })
+ *     draft.push({ name: "item2" })
+ *   })
+ * }
+ *
+ * // TreeRef example - pass around refs without exposing the doc
+ * function addStates(states: TreeRef<StateShape>) {
+ *   change(states, draft => {
+ *     draft.createNode({ name: "idle" })
+ *     draft.createNode({ name: "running" })
+ *   })
+ * }
  * ```
  */
 declare function change<Shape extends DocShape>(doc: TypedDoc<Shape>, fn: (draft: Mutable<Shape>) => void): TypedDoc<Shape>;
+declare function change<DataShape extends StructContainerShape>(ref: TreeRef<DataShape>, fn: (draft: TreeRef<DataShape>) => void): TreeRef<DataShape>;
+declare function change<DataShape extends StructContainerShape>(ref: TreeRefInterface<DataShape>, fn: (draft: TreeRefInterface<DataShape>) => void): TreeRefInterface<DataShape>;
+declare function change<NestedShapes extends Record<string, ContainerOrValueShape>>(ref: StructRef<NestedShapes>, fn: (draft: StructRef<NestedShapes>) => void): StructRef<NestedShapes>;
+declare function change<T extends TypedRef<ContainerShape>>(ref: T, fn: (draft: T) => void): T;
 /**
  * Access the underlying LoroDoc for advanced operations.
  * Works on both TypedDoc and any typed ref (TextRef, CounterRef, ListRef, etc.).
@@ -1448,6 +1544,7 @@ declare function change<Shape extends DocShape>(doc: TypedDoc<Shape>, fn: (draft
 declare function getLoroDoc<Shape extends DocShape>(doc: TypedDoc<Shape>): LoroDoc;
 declare function getLoroDoc<Shape extends ContainerShape>(ref: TypedRef<Shape>): LoroDoc;
 declare function getLoroDoc<DataShape extends StructContainerShape>(ref: TreeRef<DataShape>): LoroDoc;
+declare function getLoroDoc<DataShape extends StructContainerShape>(ref: TreeRefInterface<DataShape>): LoroDoc;
 /**
  * Access the underlying Loro container from a typed ref.
  * Returns the correctly-typed container based on the ref type.
@@ -1480,7 +1577,35 @@ declare function getLoroContainer(ref: TypedRef<RecordContainerShape>): LoroMap;
 declare function getLoroContainer(ref: TypedRef<StructContainerShape>): LoroMap;
 declare function getLoroContainer<NestedShapes extends Record<string, ContainerOrValueShape>>(ref: StructRef<NestedShapes>): LoroMap;
 declare function getLoroContainer<DataShape extends StructContainerShape>(ref: TreeRef<DataShape>): LoroTree;
+declare function getLoroContainer<DataShape extends StructContainerShape>(ref: TreeRefInterface<DataShape>): LoroTree;
 declare function getLoroContainer<Shape extends ContainerShape>(ref: TypedRef<Shape>): ShapeToContainer<Shape>;
+/**
+ * Creates a new TypedDoc at a specified version (frontiers).
+ * The forked doc will only contain history before the specified frontiers.
+ * The forked doc has a different PeerID from the original.
+ *
+ * For raw LoroDoc access, use: `loro(doc).doc.forkAt(frontiers)`
+ *
+ * @param doc - The TypedDoc to fork
+ * @param frontiers - The version to fork at (obtained from `loro(doc).doc.frontiers()`)
+ * @returns A new TypedDoc with the same schema at the specified version
+ *
+ * @example
+ * ```typescript
+ * import { forkAt, loro } from "@loro-extended/change"
+ *
+ * const doc = createTypedDoc(schema);
+ * doc.title.update("Hello");
+ * const frontiers = loro(doc).doc.frontiers();
+ * doc.title.update("World");
+ *
+ * // Fork at the earlier version
+ * const forkedDoc = forkAt(doc, frontiers);
+ * console.log(forkedDoc.title.toString()); // "Hello"
+ * console.log(doc.title.toString()); // "World"
+ * ```
+ */
+declare function forkAt<Shape extends DocShape>(doc: TypedDoc<Shape>, frontiers: Frontiers): TypedDoc<Shape>;
 
 /**
  * Overlays CRDT state with placeholder defaults
@@ -1623,4 +1748,4 @@ declare function createPlaceholderProxy<T extends object>(target: T): T;
  */
 declare function validatePlaceholder<T extends DocShape>(placeholder: unknown, schema: T): Infer<T>;
 
-export { type AnyContainerShape, type AnyValueShape, type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, CounterRef, type DiscriminatedUnionValueShape, type DocShape, type Infer, type InferMutableType, type InferPlaceholderType, type InferRaw, LORO_SYMBOL, type ListContainerShape, ListRef, type LoroCounterRef, type LoroListRef, type LoroMapRef, type LoroRefBase, type LoroTextRef, type LoroTreeRef, type LoroTypedDocRef, type MapContainerShape, type MovableListContainerShape, MovableListRef, type Mutable, type ObjectValueShape, type PathBuilder, type PathNode, type PathSegment, type PathSelector, type RecordContainerShape, RecordRef, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StructContainerShape, type StructRef, type StructValueShape, type TextContainerShape, TextRef, type TreeContainerShape, type TreeNodeJSON, TreeNodeRef, TreeRef, type TreeRefInterface, type TypedDoc, type UnionValueShape, type ValueShape, type WithNullable, type WithPlaceholder, change, compileToJsonPath, createPathBuilder, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, evaluatePath, evaluatePathOnValue, getLoroContainer, getLoroDoc, hasWildcard, loro, mergeValue, overlayPlaceholder, validatePlaceholder };
+export { type AnyContainerShape, type AnyValueShape, type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, CounterRef, type DiscriminatedUnionValueShape, type DocShape, type Frontiers, type Infer, type InferMutableType, type InferPlaceholderType, type InferRaw, LORO_SYMBOL, type ListContainerShape, ListRef, type LoroCounterRef, type LoroListRef, type LoroMapRef, type LoroRefBase, type LoroTextRef, type LoroTreeRef, type LoroTypedDocRef, type MapContainerShape, type MovableListContainerShape, MovableListRef, type Mutable, type ObjectValueShape, type PathBuilder, type PathNode, type PathSegment, type PathSelector, type RecordContainerShape, RecordRef, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StructContainerShape, type StructRef, type StructValueShape, type TextContainerShape, TextRef, type TreeContainerShape, type TreeNodeJSON, TreeNodeRef, TreeRef, type TreeRefInterface, type TypedDoc, type UnionValueShape, type ValueShape, type WithNullable, type WithPlaceholder, change, compileToJsonPath, createPathBuilder, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, evaluatePath, evaluatePathOnValue, forkAt, getLoroContainer, getLoroDoc, hasWildcard, loro, mergeValue, overlayPlaceholder, validatePlaceholder };