@loro-extended/change 3.0.0 → 5.0.0

package/dist/index.js

@@ -99,12 +99,27 @@ function deriveValueShapePlaceholder(shape) {
   }
 }
 
+// src/loro.ts
+var LORO_SYMBOL = /* @__PURE__ */ Symbol.for("loro-extended:loro");
+function loro(refOrDoc) {
+  const loroNamespace = refOrDoc[LORO_SYMBOL];
+  if (!loroNamespace) {
+    throw new Error(
+      "Invalid argument: expected TypedRef, TreeRef, or TypedDoc with loro() support"
+    );
+  }
+  return loroNamespace;
+}
+
 // src/functional-helpers.ts
 function change(doc, fn) {
-  return doc.$.change(fn);
+  return doc.change(fn);
 }
-function getLoroDoc(doc) {
-  return doc.$.loroDoc;
+function getLoroDoc(docOrRef) {
+  return loro(docOrRef).doc;
+}
+function getLoroContainer(ref) {
+  return loro(ref).container;
 }
 
 // src/utils/type-guards.ts
@@ -124,7 +139,8 @@ function isValueShape(schema) {
     "record",
     "array",
     "union",
-    "discriminatedUnion"
+    "discriminatedUnion",
+    "any"
   ].includes(schema.valueType);
 }
 function isObjectValue(value) {
@@ -199,8 +215,13 @@ function mergeValue(shape, crdtValue, placeholderValue) {
       }
       return result;
     }
-    case "tree":
-      return crdtValue !== void 0 ? crdtValue : placeholderValue ?? [];
+    case "tree": {
+      if (crdtValue === void 0) {
+        return placeholderValue ?? [];
+      }
+      const treeShape = shape;
+      return transformTreeNodes(crdtValue, treeShape.shape);
+    }
     case "record": {
       if (!isObjectValue(crdtValue) && crdtValue !== void 0) {
         throw new Error("record crdt must be object");
@@ -258,6 +279,23 @@ function mergeDiscriminatedUnion(shape, crdtValue, placeholderValue) {
   const effectivePlaceholderValue = placeholderDiscriminant === discriminantValue ? placeholderValue : void 0;
   return mergeValue(variantShape, crdtValue, effectivePlaceholderValue);
 }
+function transformTreeNodes(nodes, dataShape) {
+  const dataPlaceholder = deriveShapePlaceholder(dataShape);
+  return nodes.map((node) => transformTreeNode(node, dataShape, dataPlaceholder));
+}
+function transformTreeNode(node, dataShape, dataPlaceholder) {
+  const mergedData = mergeValue(dataShape, node.meta, dataPlaceholder);
+  return {
+    id: node.id,
+    parent: node.parent,
+    index: node.index,
+    fractionalIndex: node.fractional_index,
+    data: mergedData,
+    children: node.children.map(
+      (child) => transformTreeNode(child, dataShape, dataPlaceholder)
+    )
+  };
+}
 
 // src/path-builder.ts
 function createPathSelector(segments) {
@@ -373,7 +411,7 @@ function hasWildcard(segments) {
 
 // src/path-evaluator.ts
 function evaluatePath(doc, selector) {
-  const json = doc.$.toJSON();
+  const json = doc.toJSON();
   return evaluatePathOnValue(json, selector.__segments);
 }
 function evaluatePathOnValue(value, segments) {
@@ -562,10 +600,32 @@ var Shape = {
       }
     });
   },
+  /**
+   * Creates a tree container shape for hierarchical data structures.
+   * Each node in the tree has typed metadata defined by the data shape.
+   *
+   * @example
+   * ```typescript
+   * const StateNodeDataShape = Shape.struct({
+   *   name: Shape.text(),
+   *   facts: Shape.record(Shape.plain.any()),
+   * })
+   *
+   * const Schema = Shape.doc({
+   *   states: Shape.tree(StateNodeDataShape),
+   * })
+   *
+   * doc.change(draft => {
+   *   const root = draft.states.createNode({ name: "idle", facts: {} })
+   *   const child = root.createNode({ name: "running", facts: {} })
+   *   child.data.name = "active"
+   * })
+   * ```
+   */
   tree: (shape) => ({
     _type: "tree",
     shape,
-    _plain: {},
+    _plain: [],
     _mutable: {},
     _placeholder: []
   }),
@@ -1037,52 +1097,76 @@ var JsonPatchApplicator = class {
 };
 
 // src/typed-refs/base.ts
-var TypedRef = class {
-  constructor(_params) {
-    this._params = _params;
+var INTERNAL_SYMBOL = /* @__PURE__ */ Symbol.for("loro-extended:internal");
+var BaseRefInternals = class {
+  constructor(params) {
+    this.params = params;
+  }
+  cachedContainer;
+  loroNamespace;
+  /** Get the underlying Loro container (cached) */
+  getContainer() {
+    if (!this.cachedContainer) {
+      this.cachedContainer = this.params.getContainer();
+    }
+    return this.cachedContainer;
+  }
+  /** Commit changes if autoCommit is enabled */
+  commitIfAuto() {
+    if (this.params.autoCommit) {
+      this.params.getDoc().commit();
+    }
   }
-  _cachedContainer;
-  get shape() {
-    return this._params.shape;
+  /** Get the shape for this ref */
+  getShape() {
+    return this.params.shape;
   }
-  get placeholder() {
-    return this._params.placeholder;
+  /** Get the placeholder value */
+  getPlaceholder() {
+    return this.params.placeholder;
   }
-  get readonly() {
-    return !!this._params.readonly;
+  /** Check if autoCommit is enabled */
+  getAutoCommit() {
+    return !!this.params.autoCommit;
   }
-  get autoCommit() {
-    return !!this._params.autoCommit;
+  /** Check if in batched mutation mode */
+  getBatchedMutation() {
+    return !!this.params.batchedMutation;
   }
-  get doc() {
-    return this._params.getDoc?.();
+  /** Get the LoroDoc */
+  getDoc() {
+    return this.params.getDoc();
   }
-  /**
-   * Commits changes if autoCommit is enabled.
-   * Call this after any mutation operation.
-   */
-  commitIfAuto() {
-    if (this.autoCommit && this.doc) {
-      this.doc.commit();
+  /** Get the loro namespace (cached) */
+  getLoroNamespace() {
+    if (!this.loroNamespace) {
+      this.loroNamespace = this.createLoroNamespace();
     }
+    return this.loroNamespace;
+  }
+  /** Create the loro() namespace object - subclasses override for specific types */
+  createLoroNamespace() {
+    const self = this;
+    return {
+      get doc() {
+        return self.params.getDoc();
+      },
+      get container() {
+        return self.getContainer();
+      },
+      subscribe(callback) {
+        return self.getContainer().subscribe(callback);
+      }
+    };
   }
+};
+var TypedRef = class {
   /**
-   * Throws an error if this ref is in readonly mode.
-   * Call this at the start of any mutating method.
-   * @deprecated Mutations are always allowed now; this will be removed.
+   * Access the loro() namespace via the well-known symbol.
+   * This is used by the loro() function to access CRDT internals.
    */
-  assertMutable() {
-    if (this.readonly) {
-      throw new Error("Cannot modify readonly ref");
-    }
-  }
-  get container() {
-    if (!this._cachedContainer) {
-      const container = this._params.getContainer();
-      this._cachedContainer = container;
-      return container;
-    }
-    return this._cachedContainer;
+  get [LORO_SYMBOL]() {
+    return this[INTERNAL_SYMBOL].getLoroNamespace();
   }
 };
 
@@ -1096,42 +1180,73 @@ import {
   LoroTree
 } from "loro-crdt";
 
-// src/typed-refs/counter.ts
-var CounterRef = class extends TypedRef {
-  // Track if we've materialized the container (made any changes)
-  _materialized = false;
-  get container() {
-    return super.container;
-  }
-  absorbPlainValues() {
-  }
+// src/typed-refs/counter-ref-internals.ts
+var CounterRefInternals = class extends BaseRefInternals {
+  materialized = false;
+  /** Increment the counter value */
   increment(value = 1) {
-    this.assertMutable();
-    this._materialized = true;
-    this.container.increment(value);
+    this.materialized = true;
+    this.getContainer().increment(value);
     this.commitIfAuto();
   }
+  /** Decrement the counter value */
   decrement(value = 1) {
-    this.assertMutable();
-    this._materialized = true;
-    this.container.decrement(value);
+    this.materialized = true;
+    this.getContainer().decrement(value);
     this.commitIfAuto();
   }
-  /**
-   * Returns the counter value.
-   * If the counter hasn't been materialized (no operations performed),
-   * returns the placeholder value if available.
-   */
-  get value() {
-    const containerValue = this.container.value;
-    if (containerValue !== 0 || this._materialized) {
+  /** Get the current counter value */
+  getValue() {
+    const container = this.getContainer();
+    const containerValue = container.value;
+    if (containerValue !== 0 || this.materialized) {
       return containerValue;
     }
-    if (this.placeholder !== void 0) {
-      return this.placeholder;
+    const placeholder = this.getPlaceholder();
+    if (placeholder !== void 0) {
+      return placeholder;
     }
     return containerValue;
   }
+  /** No plain values in counter */
+  absorbPlainValues() {
+  }
+  /** Create the loro namespace for counter */
+  createLoroNamespace() {
+    const self = this;
+    return {
+      get doc() {
+        return self.getDoc();
+      },
+      get container() {
+        return self.getContainer();
+      },
+      subscribe(callback) {
+        return self.getContainer().subscribe(callback);
+      }
+    };
+  }
+};
+
+// src/typed-refs/counter-ref.ts
+var CounterRef = class extends TypedRef {
+  [INTERNAL_SYMBOL];
+  constructor(params) {
+    super();
+    this[INTERNAL_SYMBOL] = new CounterRefInternals(params);
+  }
+  /** Increment the counter by the given value (default 1) */
+  increment(value) {
+    this[INTERNAL_SYMBOL].increment(value);
+  }
+  /** Decrement the counter by the given value (default 1) */
+  decrement(value) {
+    this[INTERNAL_SYMBOL].decrement(value);
+  }
+  /** Get the current counter value */
+  get value() {
+    return this[INTERNAL_SYMBOL].getValue();
+  }
   valueOf() {
     return this.value;
   }
@@ -1280,75 +1395,41 @@ function convertInputToRef(value, shape) {
   }
 }
 
-// src/typed-refs/list-base.ts
-var ListRefBase = class extends TypedRef {
-  // Cache for items returned by array methods to track mutations
+// src/typed-refs/list-ref-base.ts
+var ListRefBaseInternals = class extends BaseRefInternals {
   itemCache = /* @__PURE__ */ new Map();
-  get container() {
-    return super.container;
-  }
-  get shape() {
-    return super.shape;
-  }
-  absorbPlainValues() {
-    for (const [index, cachedItem] of this.itemCache.entries()) {
-      if (cachedItem) {
-        if (isValueShape(this.shape.shape)) {
-          this.absorbValueAtIndex(index, cachedItem);
-        } else {
-          if (cachedItem && typeof cachedItem === "object" && "absorbPlainValues" in cachedItem) {
-            ;
-            cachedItem.absorbPlainValues();
-          }
-        }
-      }
-    }
-    this.itemCache.clear();
-  }
-  insertWithConversion(index, item) {
-    const convertedItem = convertInputToRef(item, this.shape.shape);
-    if (isContainer(convertedItem)) {
-      this.container.insertContainer(index, convertedItem);
-    } else {
-      this.container.insert(index, convertedItem);
-    }
-  }
-  pushWithConversion(item) {
-    const convertedItem = convertInputToRef(item, this.shape.shape);
-    if (isContainer(convertedItem)) {
-      this.container.pushContainer(convertedItem);
-    } else {
-      this.container.push(convertedItem);
-    }
-  }
+  /** Get typed ref params for creating child refs at an index */
   getTypedRefParams(index, shape) {
     return {
       shape,
       placeholder: void 0,
       // List items don't have placeholder
       getContainer: () => {
-        const containerItem = this.container.get(index);
+        const container = this.getContainer();
+        const containerItem = container.get(index);
         if (!containerItem || !isContainer(containerItem)) {
           throw new Error(`No container found at index ${index}`);
         }
         return containerItem;
       },
-      readonly: this.readonly,
-      autoCommit: this._params.autoCommit,
-      getDoc: this._params.getDoc
+      autoCommit: this.getAutoCommit(),
+      batchedMutation: this.getBatchedMutation(),
+      getDoc: () => this.getDoc()
     };
   }
-  // Get item for predicate functions - always returns plain Item for filtering logic
+  /** Get item for predicate functions (returns plain value) */
   getPredicateItem(index) {
+    const shape = this.getShape();
+    const container = this.getContainer();
     const cachedItem = this.itemCache.get(index);
-    if (cachedItem && isValueShape(this.shape.shape)) {
+    if (cachedItem && isValueShape(shape.shape)) {
       return cachedItem;
     }
-    const containerItem = this.container.get(index);
+    const containerItem = container.get(index);
     if (containerItem === void 0) {
       return void 0;
     }
-    if (isValueShape(this.shape.shape)) {
+    if (isValueShape(shape.shape)) {
       return containerItem;
     } else {
       if (isContainer(containerItem)) {
@@ -1363,54 +1444,154 @@ var ListRefBase = class extends TypedRef {
       return containerItem;
     }
   }
-  // Get item for return values - returns MutableItem that can be mutated
+  /** Get mutable item for return values (returns ref or cached value) */
   getMutableItem(index) {
-    let cachedItem = this.itemCache.get(index);
-    if (cachedItem) {
-      return cachedItem;
-    }
-    const containerItem = this.container.get(index);
+    const shape = this.getShape();
+    const container = this.getContainer();
+    const containerItem = container.get(index);
     if (containerItem === void 0) {
       return void 0;
     }
-    if (isValueShape(this.shape.shape)) {
+    if (isValueShape(shape.shape)) {
+      if (!this.getBatchedMutation()) {
+        return containerItem;
+      }
+      let cachedItem2 = this.itemCache.get(index);
+      if (cachedItem2) {
+        return cachedItem2;
+      }
       if (typeof containerItem === "object" && containerItem !== null) {
-        cachedItem = JSON.parse(JSON.stringify(containerItem));
+        cachedItem2 = JSON.parse(JSON.stringify(containerItem));
       } else {
-        cachedItem = containerItem;
-      }
-      if (!this.readonly) {
-        this.itemCache.set(index, cachedItem);
+        cachedItem2 = containerItem;
       }
-      return cachedItem;
-    } else {
+      this.itemCache.set(index, cachedItem2);
+      return cachedItem2;
+    }
+    let cachedItem = this.itemCache.get(index);
+    if (!cachedItem) {
       cachedItem = createContainerTypedRef(
-        this.getTypedRefParams(index, this.shape.shape)
+        this.getTypedRefParams(index, shape.shape)
       );
       this.itemCache.set(index, cachedItem);
-      if (this.readonly) {
-        return unwrapReadonlyPrimitive(
-          cachedItem,
-          this.shape.shape
-        );
+    }
+    return cachedItem;
+  }
+  /** Insert with automatic conversion */
+  insertWithConversion(index, item) {
+    const shape = this.getShape();
+    const container = this.getContainer();
+    const convertedItem = convertInputToRef(item, shape.shape);
+    if (isContainer(convertedItem)) {
+      container.insertContainer(index, convertedItem);
+    } else {
+      container.insert(index, convertedItem);
+    }
+  }
+  /** Push with automatic conversion */
+  pushWithConversion(item) {
+    const shape = this.getShape();
+    const container = this.getContainer();
+    const convertedItem = convertInputToRef(item, shape.shape);
+    if (isContainer(convertedItem)) {
+      container.pushContainer(convertedItem);
+    } else {
+      container.push(convertedItem);
+    }
+  }
+  /** Absorb value at specific index (for value shapes) - subclasses override */
+  absorbValueAtIndex(_index, _value) {
+    throw new Error("absorbValueAtIndex must be implemented by subclass");
+  }
+  /** Update cache indices after a delete operation */
+  updateCacheForDelete(deleteIndex, deleteLen) {
+    const newCache = /* @__PURE__ */ new Map();
+    for (const [cachedIndex, cachedItem] of this.itemCache.entries()) {
+      if (cachedIndex < deleteIndex) {
+        newCache.set(cachedIndex, cachedItem);
+      } else if (cachedIndex >= deleteIndex + deleteLen) {
+        newCache.set(cachedIndex - deleteLen, cachedItem);
+      }
+    }
+    this.itemCache = newCache;
+  }
+  /** Update cache indices after an insert operation */
+  updateCacheForInsert(insertIndex) {
+    const newCache = /* @__PURE__ */ new Map();
+    for (const [cachedIndex, cachedItem] of this.itemCache.entries()) {
+      if (cachedIndex < insertIndex) {
+        newCache.set(cachedIndex, cachedItem);
+      } else {
+        newCache.set(cachedIndex + 1, cachedItem);
+      }
+    }
+    this.itemCache = newCache;
+  }
+  /** Absorb mutated plain values back into Loro containers */
+  absorbPlainValues() {
+    const shape = this.getShape();
+    for (const [index, cachedItem] of this.itemCache.entries()) {
+      if (cachedItem) {
+        if (isValueShape(shape.shape)) {
+          this.absorbValueAtIndex(index, cachedItem);
+        } else {
+          if (cachedItem && typeof cachedItem === "object" && INTERNAL_SYMBOL in cachedItem) {
+            ;
+            cachedItem[INTERNAL_SYMBOL].absorbPlainValues();
+          }
+        }
       }
-      return cachedItem;
     }
+    this.itemCache.clear();
+  }
+  /** Create the loro namespace for list */
+  createLoroNamespace() {
+    const self = this;
+    return {
+      get doc() {
+        return self.getDoc();
+      },
+      get container() {
+        return self.getContainer();
+      },
+      subscribe(callback) {
+        return self.getContainer().subscribe(
+          callback
+        );
+      },
+      pushContainer(container) {
+        const result = self.getContainer().pushContainer(container);
+        self.commitIfAuto();
+        return result;
+      },
+      insertContainer(index, container) {
+        const result = self.getContainer().insertContainer(index, container);
+        self.commitIfAuto();
+        return result;
+      }
+    };
+  }
+};
+var ListRefBase = class extends TypedRef {
+  [INTERNAL_SYMBOL];
+  constructor(params) {
+    super();
+    this[INTERNAL_SYMBOL] = this.createInternals(params);
   }
   // Array-like methods for better developer experience
   // DUAL INTERFACE: Predicates get Item (plain data), return values are MutableItem (mutable)
   find(predicate) {
     for (let i = 0; i < this.length; i++) {
-      const predicateItem = this.getPredicateItem(i);
+      const predicateItem = this[INTERNAL_SYMBOL].getPredicateItem(i);
       if (predicate(predicateItem, i)) {
-        return this.getMutableItem(i);
+        return this[INTERNAL_SYMBOL].getMutableItem(i);
       }
     }
     return void 0;
   }
   findIndex(predicate) {
     for (let i = 0; i < this.length; i++) {
-      const predicateItem = this.getPredicateItem(i);
+      const predicateItem = this[INTERNAL_SYMBOL].getPredicateItem(i);
       if (predicate(predicateItem, i)) {
         return i;
       }
@@ -1420,7 +1601,7 @@ var ListRefBase = class extends TypedRef {
   map(callback) {
     const result = [];
     for (let i = 0; i < this.length; i++) {
-      const predicateItem = this.getPredicateItem(i);
+      const predicateItem = this[INTERNAL_SYMBOL].getPredicateItem(i);
       result.push(callback(predicateItem, i));
     }
     return result;
@@ -1428,22 +1609,22 @@ var ListRefBase = class extends TypedRef {
   filter(predicate) {
     const result = [];
     for (let i = 0; i < this.length; i++) {
-      const predicateItem = this.getPredicateItem(i);
+      const predicateItem = this[INTERNAL_SYMBOL].getPredicateItem(i);
       if (predicate(predicateItem, i)) {
-        result.push(this.getMutableItem(i));
+        result.push(this[INTERNAL_SYMBOL].getMutableItem(i));
       }
     }
     return result;
   }
   forEach(callback) {
     for (let i = 0; i < this.length; i++) {
-      const predicateItem = this.getPredicateItem(i);
+      const predicateItem = this[INTERNAL_SYMBOL].getPredicateItem(i);
       callback(predicateItem, i);
     }
   }
   some(predicate) {
     for (let i = 0; i < this.length; i++) {
-      const predicateItem = this.getPredicateItem(i);
+      const predicateItem = this[INTERNAL_SYMBOL].getPredicateItem(i);
       if (predicate(predicateItem, i)) {
         return true;
       }
@@ -1452,7 +1633,7 @@ var ListRefBase = class extends TypedRef {
   }
   every(predicate) {
     for (let i = 0; i < this.length; i++) {
-      const predicateItem = this.getPredicateItem(i);
+      const predicateItem = this[INTERNAL_SYMBOL].getPredicateItem(i);
       if (!predicate(predicateItem, i)) {
         return false;
       }
@@ -1465,55 +1646,55 @@ var ListRefBase = class extends TypedRef {
     const endIndex = end === void 0 ? len : end < 0 ? Math.max(len + end, 0) : Math.min(end, len);
     const result = [];
     for (let i = startIndex; i < endIndex; i++) {
-      result.push(this.getMutableItem(i));
+      result.push(this[INTERNAL_SYMBOL].getMutableItem(i));
     }
     return result;
   }
   insert(index, item) {
-    this.assertMutable();
-    this.updateCacheForInsert(index);
-    this.insertWithConversion(index, item);
-    this.commitIfAuto();
+    this[INTERNAL_SYMBOL].updateCacheForInsert(index);
+    this[INTERNAL_SYMBOL].insertWithConversion(index, item);
+    this[INTERNAL_SYMBOL].commitIfAuto();
   }
   delete(index, len) {
-    this.assertMutable();
-    this.updateCacheForDelete(index, len);
-    this.container.delete(index, len);
-    this.commitIfAuto();
+    this[INTERNAL_SYMBOL].updateCacheForDelete(index, len);
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    container.delete(index, len);
+    this[INTERNAL_SYMBOL].commitIfAuto();
   }
   push(item) {
-    this.assertMutable();
-    this.pushWithConversion(item);
-    this.commitIfAuto();
+    this[INTERNAL_SYMBOL].pushWithConversion(item);
+    this[INTERNAL_SYMBOL].commitIfAuto();
   }
   pushContainer(container) {
-    this.assertMutable();
-    const result = this.container.pushContainer(container);
-    this.commitIfAuto();
+    const loroContainer = this[INTERNAL_SYMBOL].getContainer();
+    const result = loroContainer.pushContainer(container);
+    this[INTERNAL_SYMBOL].commitIfAuto();
     return result;
   }
   insertContainer(index, container) {
-    this.assertMutable();
-    const result = this.container.insertContainer(index, container);
-    this.commitIfAuto();
+    const loroContainer = this[INTERNAL_SYMBOL].getContainer();
+    const result = loroContainer.insertContainer(index, container);
+    this[INTERNAL_SYMBOL].commitIfAuto();
     return result;
   }
   get(index) {
-    return this.getMutableItem(index);
+    return this[INTERNAL_SYMBOL].getMutableItem(index);
   }
   toArray() {
     const result = [];
     for (let i = 0; i < this.length; i++) {
-      result.push(this.getPredicateItem(i));
+      result.push(this[INTERNAL_SYMBOL].getPredicateItem(i));
     }
     return result;
   }
   toJSON() {
-    const nativeJson = this.container.toJSON();
-    if (isContainerShape(this.shape.shape) || isValueShape(this.shape.shape) && this.shape.shape.valueType === "struct") {
-      const itemPlaceholder = deriveShapePlaceholder(this.shape.shape);
+    const shape = this[INTERNAL_SYMBOL].getShape();
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    const nativeJson = container.toJSON();
+    if (isContainerShape(shape.shape) || isValueShape(shape.shape) && shape.shape.valueType === "struct") {
+      const itemPlaceholder = deriveShapePlaceholder(shape.shape);
       return nativeJson.map(
-        (item) => mergeValue(this.shape.shape, item, itemPlaceholder)
+        (item) => mergeValue(shape.shape, item, itemPlaceholder)
       );
     }
     return nativeJson ?? [];
@@ -1523,7 +1704,10 @@ var ListRefBase = class extends TypedRef {
     return {
       next: () => {
         if (index < this.length) {
-          return { value: this.getMutableItem(index++), done: false };
+          return {
+            value: this[INTERNAL_SYMBOL].getMutableItem(index++),
+            done: false
+          };
         }
         return { value: void 0, done: true };
       },
@@ -1533,63 +1717,59 @@ var ListRefBase = class extends TypedRef {
     };
   }
   get length() {
-    return this.container.length;
-  }
-  // Update cache indices when items are deleted
-  updateCacheForDelete(deleteIndex, deleteLen) {
-    const newCache = /* @__PURE__ */ new Map();
-    for (const [cachedIndex, cachedItem] of this.itemCache.entries()) {
-      if (cachedIndex < deleteIndex) {
-        newCache.set(cachedIndex, cachedItem);
-      } else if (cachedIndex >= deleteIndex + deleteLen) {
-        newCache.set(cachedIndex - deleteLen, cachedItem);
-      }
-    }
-    this.itemCache = newCache;
-  }
-  // Update cache indices when items are inserted
-  updateCacheForInsert(insertIndex) {
-    const newCache = /* @__PURE__ */ new Map();
-    for (const [cachedIndex, cachedItem] of this.itemCache.entries()) {
-      if (cachedIndex < insertIndex) {
-        newCache.set(cachedIndex, cachedItem);
-      } else {
-        newCache.set(cachedIndex + 1, cachedItem);
-      }
-    }
-    this.itemCache = newCache;
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.length;
   }
 };
 
-// src/typed-refs/list.ts
-var ListRef = class extends ListRefBase {
-  get container() {
-    return super.container;
-  }
+// src/typed-refs/list-ref-internals.ts
+var ListRefInternals = class extends ListRefBaseInternals {
+  /** Absorb value at specific index for LoroList */
   absorbValueAtIndex(index, value) {
-    this.container.delete(index, 1);
-    this.container.insert(index, value);
+    const container = this.getContainer();
+    container.delete(index, 1);
+    container.insert(index, value);
   }
 };
 
-// src/typed-refs/movable-list.ts
-var MovableListRef = class extends ListRefBase {
-  get container() {
-    return super.container;
+// src/typed-refs/list-ref.ts
+var ListRef = class extends ListRefBase {
+  createInternals(params) {
+    return new ListRefInternals(params);
   }
+};
+
+// src/typed-refs/movable-list-ref-internals.ts
+var MovableListRefInternals = class extends ListRefBaseInternals {
+  /** Absorb value at specific index for LoroMovableList */
   absorbValueAtIndex(index, value) {
-    this.container.set(index, value);
+    const container = this.getContainer();
+    container.set(index, value);
   }
+  /** Move an item from one index to another */
   move(from, to) {
-    this.assertMutable();
-    this.container.move(from, to);
+    const container = this.getContainer();
+    container.move(from, to);
     this.commitIfAuto();
   }
+  /** Set an item at a specific index */
   set(index, item) {
-    this.assertMutable();
-    const result = this.container.set(index, item);
+    const container = this.getContainer();
+    container.set(index, item);
     this.commitIfAuto();
-    return result;
+  }
+};
+
+// src/typed-refs/movable-list-ref.ts
+var MovableListRef = class extends ListRefBase {
+  createInternals(params) {
+    return new MovableListRefInternals(params);
+  }
+  move(from, to) {
+    this[INTERNAL_SYMBOL].move(from, to);
+  }
+  set(index, item) {
+    this[INTERNAL_SYMBOL].set(index, item);
   }
 };
 
@@ -1597,7 +1777,7 @@ var MovableListRef = class extends ListRefBase {
 var recordProxyHandler = {
   get: (target, prop) => {
     if (typeof prop === "string" && !(prop in target)) {
-      return target.getRef(prop);
+      return target[INTERNAL_SYMBOL].getRef(prop);
     }
     return Reflect.get(target, prop);
   },
@@ -1683,20 +1863,12 @@ var movableListProxyHandler = {
   }
 };
 
-// src/typed-refs/record.ts
-var RecordRef = class extends TypedRef {
+// src/typed-refs/record-ref-internals.ts
+var RecordRefInternals = class extends BaseRefInternals {
   refCache = /* @__PURE__ */ new Map();
-  get shape() {
-    return super.shape;
-  }
-  get container() {
-    return super.container;
-  }
-  absorbPlainValues() {
-    absorbCachedPlainValues(this.refCache, () => this.container);
-  }
+  /** Get typed ref params for creating child refs at a key */
   getTypedRefParams(key, shape) {
-    let placeholder = this.placeholder?.[key];
+    let placeholder = this.getPlaceholder()?.[key];
     if (placeholder === void 0) {
       placeholder = deriveShapePlaceholder(shape);
     }
@@ -1706,74 +1878,83 @@ var RecordRef = class extends TypedRef {
       );
     }
     const LoroContainer = containerConstructor[shape._type];
+    const container = this.getContainer();
     return {
       shape,
       placeholder,
-      getContainer: () => this.container.getOrCreateContainer(key, new LoroContainer()),
-      readonly: this.readonly,
-      autoCommit: this._params.autoCommit,
-      getDoc: this._params.getDoc
+      getContainer: () => container.getOrCreateContainer(key, new LoroContainer()),
+      autoCommit: this.getAutoCommit(),
+      batchedMutation: this.getBatchedMutation(),
+      getDoc: () => this.getDoc()
     };
   }
-  /**
-   * Gets an existing ref for a key, or returns undefined if the key doesn't exist.
-   * Used for reading operations where we want optional chaining to work.
-   */
+  /** Get a ref for a key without creating (returns undefined for non-existent container keys) */
   getRef(key) {
-    if (isContainerShape(this.shape.shape)) {
-      const existing = this.container.get(key);
+    const recordShape = this.getShape();
+    const shape = recordShape.shape;
+    const container = this.getContainer();
+    if (isContainerShape(shape)) {
+      const existing = container.get(key);
       if (existing === void 0) {
         return void 0;
       }
     }
     return this.getOrCreateRef(key);
   }
-  /**
-   * Gets or creates a ref for a key.
-   * Always creates the container if it doesn't exist.
-   * This is the method used for write operations.
-   */
+  /** Get or create a ref for a key (always creates for container shapes) */
   getOrCreateRef(key) {
-    let ref = this.refCache.get(key);
-    if (!ref) {
-      const shape = this.shape.shape;
-      if (isContainerShape(shape)) {
-        ref = createContainerTypedRef(
-          this.getTypedRefParams(key, shape)
-        );
-        this.refCache.set(key, ref);
-      } else {
-        const containerValue = this.container.get(key);
+    const recordShape = this.getShape();
+    const shape = recordShape.shape;
+    const container = this.getContainer();
+    if (isValueShape(shape)) {
+      if (!this.getBatchedMutation()) {
+        const containerValue = container.get(key);
+        if (containerValue !== void 0) {
+          return containerValue;
+        }
+        const placeholder = this.getPlaceholder()?.[key];
+        if (placeholder !== void 0) {
+          return placeholder;
+        }
+        return shape._plain;
+      }
+      let ref2 = this.refCache.get(key);
+      if (!ref2) {
+        const containerValue = container.get(key);
         if (containerValue !== void 0) {
-          ref = containerValue;
+          if (typeof containerValue === "object" && containerValue !== null) {
+            ref2 = JSON.parse(JSON.stringify(containerValue));
+          } else {
+            ref2 = containerValue;
+          }
         } else {
-          const placeholder = this.placeholder?.[key];
-          if (placeholder === void 0) {
-            ref = shape._plain;
+          const placeholder = this.getPlaceholder()?.[key];
+          if (placeholder !== void 0) {
+            ref2 = placeholder;
           } else {
-            ref = placeholder;
+            ref2 = shape._plain;
           }
         }
-        if (ref !== void 0 && !this.readonly) {
-          this.refCache.set(key, ref);
-        }
+        this.refCache.set(key, ref2);
       }
+      return ref2;
     }
-    if (this.readonly && isContainerShape(this.shape.shape)) {
-      return unwrapReadonlyPrimitive(
-        ref,
-        this.shape.shape
+    let ref = this.refCache.get(key);
+    if (!ref) {
+      ref = createContainerTypedRef(
+        this.getTypedRefParams(key, shape)
       );
+      this.refCache.set(key, ref);
     }
     return ref;
   }
-  get(key) {
-    return this.getRef(key);
-  }
+  /** Set a value at a key */
   set(key, value) {
-    this.assertMutable();
-    if (isValueShape(this.shape.shape)) {
-      this.container.set(key, value);
+    const recordShape = this.getShape();
+    const shape = recordShape.shape;
+    const container = this.getContainer();
+    if (isValueShape(shape)) {
+      container.set(key, value);
       this.refCache.set(key, value);
       this.commitIfAuto();
     } else {
@@ -1787,222 +1968,460 @@ var RecordRef = class extends TypedRef {
       );
     }
   }
-  setContainer(key, container) {
-    this.assertMutable();
-    const result = this.container.setContainer(key, container);
-    this.commitIfAuto();
-    return result;
-  }
+  /** Delete a key */
   delete(key) {
-    this.assertMutable();
-    this.container.delete(key);
+    const container = this.getContainer();
+    container.delete(key);
     this.refCache.delete(key);
     this.commitIfAuto();
   }
-  has(key) {
-    return this.container.get(key) !== void 0;
-  }
-  keys() {
-    return this.container.keys();
+  /** Absorb mutated plain values back into Loro containers */
+  absorbPlainValues() {
+    absorbCachedPlainValues(this.refCache, () => this.getContainer());
   }
-  values() {
-    return this.container.values();
+  /** Create the loro namespace for record */
+  createLoroNamespace() {
+    const self = this;
+    return {
+      get doc() {
+        return self.getDoc();
+      },
+      get container() {
+        return self.getContainer();
+      },
+      subscribe(callback) {
+        return self.getContainer().subscribe(callback);
+      },
+      setContainer(key, container) {
+        const result = self.getContainer().setContainer(
+          key,
+          container
+        );
+        self.commitIfAuto();
+        return result;
+      }
+    };
+  }
+};
+
+// src/typed-refs/record-ref.ts
+var RecordRef = class extends TypedRef {
+  [INTERNAL_SYMBOL];
+  constructor(params) {
+    super();
+    this[INTERNAL_SYMBOL] = new RecordRefInternals(params);
+  }
+  /** Set a value at a key */
+  set(key, value) {
+    this[INTERNAL_SYMBOL].set(key, value);
+  }
+  /** Delete a key */
+  delete(key) {
+    this[INTERNAL_SYMBOL].delete(key);
+  }
+  get(key) {
+    if (this[INTERNAL_SYMBOL].getBatchedMutation()) {
+      return this[INTERNAL_SYMBOL].getOrCreateRef(key);
+    }
+    return this[INTERNAL_SYMBOL].getRef(key);
+  }
+  setContainer(key, container) {
+    const loroContainer = this[INTERNAL_SYMBOL].getContainer();
+    const result = loroContainer.setContainer(key, container);
+    this[INTERNAL_SYMBOL].commitIfAuto();
+    return result;
+  }
+  has(key) {
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.get(key) !== void 0;
+  }
+  keys() {
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.keys();
+  }
+  values() {
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.values();
   }
   get size() {
-    return this.container.size;
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.size;
   }
   toJSON() {
-    if (this.readonly) {
-      const nativeJson = this.container.toJSON();
-      const result = {};
-      for (const key of Object.keys(nativeJson)) {
-        const nestedPlaceholderValue = deriveShapePlaceholder(this.shape.shape);
-        result[key] = mergeValue(
-          this.shape.shape,
-          nativeJson[key],
-          nestedPlaceholderValue
-        );
-      }
-      return result;
-    }
     return serializeRefToJSON(this, this.keys());
   }
 };
 
-// src/typed-refs/struct.ts
-var StructRef = class extends TypedRef {
+// src/typed-refs/struct-ref-internals.ts
+var StructRefInternals = class extends BaseRefInternals {
   propertyCache = /* @__PURE__ */ new Map();
-  constructor(params) {
-    super(params);
-    this.createLazyProperties();
-  }
-  get shape() {
-    return super.shape;
-  }
-  get container() {
-    return super.container;
-  }
-  absorbPlainValues() {
-    absorbCachedPlainValues(this.propertyCache, () => this.container);
-  }
+  /** Get typed ref params for creating child refs at a key */
   getTypedRefParams(key, shape) {
-    const placeholder = this.placeholder?.[key];
+    const placeholder = this.getPlaceholder()?.[key];
     if (!hasContainerConstructor(shape._type)) {
       throw new Error(
         `Cannot create typed ref for shape type "${shape._type}". Use Shape.any() only at the document root level.`
       );
     }
     const LoroContainer = containerConstructor[shape._type];
+    const container = this.getContainer();
     return {
       shape,
       placeholder,
-      getContainer: () => this.container.getOrCreateContainer(key, new LoroContainer()),
-      readonly: this.readonly,
-      autoCommit: this._params.autoCommit,
-      getDoc: this._params.getDoc
+      getContainer: () => container.getOrCreateContainer(key, new LoroContainer()),
+      autoCommit: this.getAutoCommit(),
+      batchedMutation: this.getBatchedMutation(),
+      getDoc: () => this.getDoc()
     };
   }
+  /** Get or create a ref for a key */
   getOrCreateRef(key, shape) {
-    let ref = this.propertyCache.get(key);
-    if (!ref) {
-      if (isContainerShape(shape)) {
-        ref = createContainerTypedRef(this.getTypedRefParams(key, shape));
-        this.propertyCache.set(key, ref);
-      } else {
-        const containerValue = this.container.get(key);
+    const structShape = this.getShape();
+    const actualShape = shape || structShape.shapes[key];
+    const container = this.getContainer();
+    if (isValueShape(actualShape)) {
+      if (!this.getBatchedMutation()) {
+        const containerValue = container.get(key);
+        if (containerValue !== void 0) {
+          return containerValue;
+        }
+        const placeholder = this.getPlaceholder()?.[key];
+        if (placeholder === void 0) {
+          throw new Error("placeholder required");
+        }
+        return placeholder;
+      }
+      let ref2 = this.propertyCache.get(key);
+      if (!ref2) {
+        const containerValue = container.get(key);
         if (containerValue !== void 0) {
-          ref = containerValue;
+          if (typeof containerValue === "object" && containerValue !== null) {
+            ref2 = JSON.parse(JSON.stringify(containerValue));
+          } else {
+            ref2 = containerValue;
+          }
         } else {
-          const placeholder = this.placeholder?.[key];
+          const placeholder = this.getPlaceholder()?.[key];
           if (placeholder === void 0) {
             throw new Error("placeholder required");
           }
-          ref = placeholder;
-        }
-        if (!this.readonly) {
-          this.propertyCache.set(key, ref);
+          ref2 = placeholder;
         }
+        this.propertyCache.set(key, ref2);
       }
-      if (ref === void 0) throw new Error("no container made");
+      return ref2;
     }
-    if (this.readonly && isContainerShape(shape)) {
-      const existing = this.container.get(key);
-      if (existing === void 0) {
-        return this.placeholder?.[key];
-      }
-      return unwrapReadonlyPrimitive(ref, shape);
+    let ref = this.propertyCache.get(key);
+    if (!ref) {
+      ref = createContainerTypedRef(
+        this.getTypedRefParams(key, actualShape)
+      );
+      this.propertyCache.set(key, ref);
     }
     return ref;
   }
-  createLazyProperties() {
-    for (const key in this.shape.shapes) {
-      const shape = this.shape.shapes[key];
-      Object.defineProperty(this, key, {
-        get: () => this.getOrCreateRef(key, shape),
-        set: (value) => {
-          this.assertMutable();
-          if (isValueShape(shape)) {
-            this.container.set(key, value);
-            this.propertyCache.set(key, value);
-          } else {
-            const ref = this.getOrCreateRef(key, shape);
-            if (assignPlainValueToTypedRef(ref, value)) {
-              return;
-            }
-            throw new Error(
-              "Cannot set container directly, modify the typed ref instead"
-            );
-          }
-        },
-        enumerable: true
-      });
+  /** Set a property value */
+  setPropertyValue(key, value) {
+    const structShape = this.getShape();
+    const shape = structShape.shapes[key];
+    const container = this.getContainer();
+    if (!shape) {
+      throw new Error(`Unknown property: ${key}`);
+    }
+    if (isValueShape(shape)) {
+      container.set(key, value);
+      this.propertyCache.set(key, value);
+      this.commitIfAuto();
+    } else {
+      const ref = this.getOrCreateRef(key, shape);
+      if (assignPlainValueToTypedRef(ref, value)) {
+        this.commitIfAuto();
+        return;
+      }
+      throw new Error(
+        "Cannot set container directly, modify the typed ref instead"
+      );
     }
   }
+  /** Delete a property */
+  deleteProperty(key) {
+    const container = this.getContainer();
+    container.delete(key);
+    this.propertyCache.delete(key);
+    this.commitIfAuto();
+  }
+  /** Absorb mutated plain values back into Loro containers */
+  absorbPlainValues() {
+    absorbCachedPlainValues(
+      this.propertyCache,
+      () => this.getContainer()
+    );
+  }
+  /** Create the loro namespace for struct */
+  createLoroNamespace() {
+    const self = this;
+    return {
+      get doc() {
+        return self.getDoc();
+      },
+      get container() {
+        return self.getContainer();
+      },
+      subscribe(callback) {
+        return self.getContainer().subscribe(callback);
+      },
+      setContainer(key, container) {
+        const result = self.getContainer().setContainer(
+          key,
+          container
+        );
+        self.commitIfAuto();
+        return result;
+      }
+    };
+  }
+};
+
+// src/typed-refs/struct-ref.ts
+var StructRefImpl = class extends TypedRef {
+  [INTERNAL_SYMBOL];
+  constructor(params) {
+    super();
+    this[INTERNAL_SYMBOL] = new StructRefInternals(params);
+  }
+  get structShape() {
+    return this[INTERNAL_SYMBOL].getShape();
+  }
   toJSON() {
-    if (this.readonly) {
-      const nativeJson = this.container.toJSON();
-      return mergeValue(
-        this.shape,
-        nativeJson,
-        this.placeholder
-      );
-    }
     return serializeRefToJSON(
       this,
-      Object.keys(this.shape.shapes)
+      Object.keys(this.structShape.shapes)
     );
   }
-  // TODO(duane): return correct type here
+  // Deprecated methods - kept for backward compatibility
+  // @deprecated Use property access instead: obj.key
   get(key) {
-    return this.container.get(key);
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.get(key);
   }
+  // @deprecated Use property assignment instead: obj.key = value
   set(key, value) {
-    this.assertMutable();
-    this.container.set(key, value);
-    this.commitIfAuto();
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    container.set(key, value);
+    this[INTERNAL_SYMBOL].commitIfAuto();
   }
+  // @deprecated Use loro(struct).setContainer() instead
   setContainer(key, container) {
-    this.assertMutable();
-    const result = this.container.setContainer(key, container);
-    this.commitIfAuto();
+    const loroContainer = this[INTERNAL_SYMBOL].getContainer();
+    const result = loroContainer.setContainer(key, container);
+    this[INTERNAL_SYMBOL].commitIfAuto();
     return result;
   }
+  // @deprecated Use delete obj.key instead
   delete(key) {
-    this.assertMutable();
-    this.container.delete(key);
-    this.commitIfAuto();
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    container.delete(key);
+    this[INTERNAL_SYMBOL].commitIfAuto();
   }
+  // @deprecated Use 'key' in obj instead
   has(key) {
-    return this.container.get(key) !== void 0;
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.get(key) !== void 0;
   }
+  // @deprecated Use Object.keys(obj) instead
   keys() {
-    return this.container.keys();
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.keys();
   }
+  // @deprecated Use Object.values(obj) instead
   values() {
-    return this.container.values();
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.values();
   }
+  // @deprecated Not standard for objects
   get size() {
-    return this.container.size;
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.size;
   }
 };
+function createStructRef(params) {
+  const impl = new StructRefImpl(params);
+  const proxy = new Proxy(impl, {
+    get(target, prop, receiver) {
+      if (prop === LORO_SYMBOL) {
+        return target[INTERNAL_SYMBOL].getLoroNamespace();
+      }
+      if (prop === INTERNAL_SYMBOL) {
+        return target[INTERNAL_SYMBOL];
+      }
+      if (prop === "toJSON") {
+        return () => serializeRefToJSON(receiver, Object.keys(target.structShape.shapes));
+      }
+      if (prop === "shape") {
+        return target.structShape;
+      }
+      if (typeof prop === "string" && prop in target.structShape.shapes) {
+        const shape = target.structShape.shapes[prop];
+        return target[INTERNAL_SYMBOL].getOrCreateRef(prop, shape);
+      }
+      return void 0;
+    },
+    set(target, prop, value) {
+      if (typeof prop === "string" && prop in target.structShape.shapes) {
+        target[INTERNAL_SYMBOL].setPropertyValue(prop, value);
+        return true;
+      }
+      return false;
+    },
+    has(target, prop) {
+      if (prop === LORO_SYMBOL || prop === INTERNAL_SYMBOL || prop === "toJSON" || prop === "shape") {
+        return true;
+      }
+      if (typeof prop === "string") {
+        return prop in target.structShape.shapes;
+      }
+      return false;
+    },
+    deleteProperty(target, prop) {
+      if (typeof prop === "string" && prop in target.structShape.shapes) {
+        target[INTERNAL_SYMBOL].deleteProperty(prop);
+        return true;
+      }
+      return false;
+    },
+    ownKeys(target) {
+      return Object.keys(target.structShape.shapes);
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      if (typeof prop === "string" && prop in target.structShape.shapes) {
+        const shape = target.structShape.shapes[prop];
+        return {
+          configurable: true,
+          enumerable: true,
+          value: target[INTERNAL_SYMBOL].getOrCreateRef(prop, shape)
+        };
+      }
+      return void 0;
+    }
+  });
+  return proxy;
+}
 
-// src/typed-refs/text.ts
-var TextRef = class extends TypedRef {
-  // Track if we've materialized the container (made any changes)
-  _materialized = false;
-  get container() {
-    return super.container;
-  }
-  absorbPlainValues() {
-  }
-  // Text methods
+// src/typed-refs/text-ref-internals.ts
+var TextRefInternals = class extends BaseRefInternals {
+  materialized = false;
+  /** Insert text at the given index */
   insert(index, content) {
-    this.assertMutable();
-    this._materialized = true;
-    this.container.insert(index, content);
+    this.materialized = true;
+    this.getContainer().insert(index, content);
     this.commitIfAuto();
   }
+  /** Delete text at the given index */
   delete(index, len) {
-    this.assertMutable();
-    this._materialized = true;
-    this.container.delete(index, len);
+    this.materialized = true;
+    this.getContainer().delete(index, len);
     this.commitIfAuto();
   }
-  /**
-   * Returns the text content.
-   * If the text hasn't been materialized (no operations performed),
-   * returns the placeholder value if available.
-   */
-  toString() {
-    const containerValue = this.container.toString();
-    if (containerValue !== "" || this._materialized) {
+  /** Update the entire text content */
+  update(text) {
+    this.materialized = true;
+    this.getContainer().update(text);
+    this.commitIfAuto();
+  }
+  /** Mark a range of text with a key-value pair */
+  mark(range, key, value) {
+    this.materialized = true;
+    this.getContainer().mark(range, key, value);
+    this.commitIfAuto();
+  }
+  /** Remove a mark from a range of text */
+  unmark(range, key) {
+    this.materialized = true;
+    this.getContainer().unmark(range, key);
+    this.commitIfAuto();
+  }
+  /** Apply a delta to the text */
+  applyDelta(delta) {
+    this.materialized = true;
+    this.getContainer().applyDelta(delta);
+    this.commitIfAuto();
+  }
+  /** Get the text as a string */
+  getStringValue() {
+    const container = this.getContainer();
+    const containerValue = container.toString();
+    if (containerValue !== "" || this.materialized) {
       return containerValue;
     }
-    if (this.placeholder !== void 0) {
-      return this.placeholder;
+    const placeholder = this.getPlaceholder();
+    if (placeholder !== void 0) {
+      return placeholder;
     }
     return containerValue;
   }
+  /** Get the text as a delta */
+  toDelta() {
+    return this.getContainer().toDelta();
+  }
+  /** Get the length of the text */
+  getLength() {
+    return this.getContainer().length;
+  }
+  /** No plain values in text */
+  absorbPlainValues() {
+  }
+  /** Create the loro namespace for text */
+  createLoroNamespace() {
+    const self = this;
+    return {
+      get doc() {
+        return self.getDoc();
+      },
+      get container() {
+        return self.getContainer();
+      },
+      subscribe(callback) {
+        return self.getContainer().subscribe(callback);
+      }
+    };
+  }
+};
+
+// src/typed-refs/text-ref.ts
+var TextRef = class extends TypedRef {
+  [INTERNAL_SYMBOL];
+  constructor(params) {
+    super();
+    this[INTERNAL_SYMBOL] = new TextRefInternals(params);
+  }
+  /** Insert text at the given index */
+  insert(index, content) {
+    this[INTERNAL_SYMBOL].insert(index, content);
+  }
+  /** Delete text at the given index */
+  delete(index, len) {
+    this[INTERNAL_SYMBOL].delete(index, len);
+  }
+  /** Update the entire text content */
+  update(text) {
+    this[INTERNAL_SYMBOL].update(text);
+  }
+  /** Mark a range of text with a key-value pair */
+  mark(range, key, value) {
+    this[INTERNAL_SYMBOL].mark(range, key, value);
+  }
+  /** Remove a mark from a range of text */
+  unmark(range, key) {
+    this[INTERNAL_SYMBOL].unmark(range, key);
+  }
+  /** Apply a delta to the text */
+  applyDelta(delta) {
+    this[INTERNAL_SYMBOL].applyDelta(delta);
+  }
+  /** Get the text as a string */
+  toString() {
+    return this[INTERNAL_SYMBOL].getStringValue();
+  }
   valueOf() {
     return this.toString();
   }
@@ -2012,62 +2431,418 @@ var TextRef = class extends TypedRef {
   [Symbol.toPrimitive](_hint) {
     return this.toString();
   }
-  update(text) {
-    this.assertMutable();
-    this._materialized = true;
-    this.container.update(text);
-    this.commitIfAuto();
+  /** Get the text as a delta */
+  toDelta() {
+    return this[INTERNAL_SYMBOL].toDelta();
   }
-  mark(range, key, value) {
-    this.assertMutable();
-    this._materialized = true;
-    this.container.mark(range, key, value);
-    this.commitIfAuto();
+  /** Get the length of the text */
+  get length() {
+    return this[INTERNAL_SYMBOL].getLength();
   }
-  unmark(range, key) {
-    this.assertMutable();
-    this._materialized = true;
-    this.container.unmark(range, key);
-    this.commitIfAuto();
+};
+
+// src/typed-refs/tree-node-ref-internals.ts
+var TreeNodeRefInternals = class {
+  constructor(params) {
+    this.params = params;
   }
-  toDelta() {
-    return this.container.toDelta();
+  dataRef;
+  /** Get the underlying LoroTreeNode */
+  getNode() {
+    return this.params.node;
   }
-  applyDelta(delta) {
-    this.assertMutable();
-    this._materialized = true;
-    this.container.applyDelta(delta);
+  /** Get the data shape for this node */
+  getDataShape() {
+    return this.params.dataShape;
+  }
+  /** Get the parent TreeRef */
+  getTreeRef() {
+    return this.params.treeRef;
+  }
+  /** Check if autoCommit is enabled */
+  getAutoCommit() {
+    return this.params.autoCommit ?? false;
+  }
+  /** Check if in batched mutation mode */
+  getBatchedMutation() {
+    return this.params.batchedMutation ?? false;
+  }
+  /** Get the LoroDoc */
+  getDoc() {
+    return this.params.getDoc();
+  }
+  /** Commit changes if autoCommit is enabled */
+  commitIfAuto() {
+    if (this.params.autoCommit) {
+      this.params.getDoc().commit();
+    }
+  }
+  /** Get or create the data StructRef */
+  getOrCreateDataRef() {
+    if (!this.dataRef) {
+      const node = this.getNode();
+      const dataShape = this.getDataShape();
+      const dataContainer = node.data;
+      if (!dataContainer) {
+        throw new Error(`Node ${node.id} has no data container`);
+      }
+      const placeholder = deriveShapePlaceholder(dataShape);
+      const refParams = {
+        shape: {
+          _type: "struct",
+          shapes: dataShape.shapes,
+          _plain: {},
+          _mutable: {},
+          _placeholder: {}
+        },
+        placeholder,
+        getContainer: () => dataContainer,
+        autoCommit: this.getAutoCommit(),
+        batchedMutation: this.getBatchedMutation(),
+        getDoc: this.params.getDoc
+      };
+      this.dataRef = createStructRef(refParams);
+    }
+    return this.dataRef;
+  }
+  /** Absorb mutated plain values back into Loro containers */
+  absorbPlainValues() {
+    if (this.dataRef) {
+      this.dataRef[INTERNAL_SYMBOL].absorbPlainValues();
+    }
+  }
+};
+
+// src/typed-refs/tree-node-ref.ts
+var TreeNodeRef = class {
+  [INTERNAL_SYMBOL];
+  constructor(params) {
+    this[INTERNAL_SYMBOL] = new TreeNodeRefInternals(params);
+  }
+  /**
+   * The unique TreeID of this node.
+   */
+  get id() {
+    return this[INTERNAL_SYMBOL].getNode().id;
+  }
+  /**
+   * Typed access to the node's metadata.
+   * This is a StructRef wrapping the node's LoroMap data container.
+   */
+  get data() {
+    return this[INTERNAL_SYMBOL].getOrCreateDataRef();
+  }
+  /**
+   * Create a child node under this node.
+   *
+   * @param initialData - Optional partial data to initialize the child with
+   * @param index - Optional position among siblings
+   * @returns The created child TreeNodeRef
+   */
+  createNode(initialData, index) {
+    const node = this[INTERNAL_SYMBOL].getNode();
+    const treeRef = this[INTERNAL_SYMBOL].getTreeRef();
+    const loroNode = node.createNode(index);
+    const nodeRef = treeRef.getOrCreateNodeRef(loroNode);
+    if (initialData) {
+      for (const [key, value] of Object.entries(initialData)) {
+        ;
+        nodeRef.data[key] = value;
+      }
+    }
+    this[INTERNAL_SYMBOL].commitIfAuto();
+    return nodeRef;
+  }
+  /**
+   * Get the parent node, if any.
+   */
+  parent() {
+    const node = this[INTERNAL_SYMBOL].getNode();
+    const treeRef = this[INTERNAL_SYMBOL].getTreeRef();
+    const parentNode = node.parent?.();
+    if (!parentNode) return void 0;
+    return treeRef.getOrCreateNodeRef(parentNode);
+  }
+  /**
+   * Get all child nodes in order.
+   */
+  children() {
+    const node = this[INTERNAL_SYMBOL].getNode();
+    const treeRef = this[INTERNAL_SYMBOL].getTreeRef();
+    const childNodes = node.children?.() || [];
+    return childNodes.map((n) => treeRef.getOrCreateNodeRef(n));
+  }
+  /**
+   * Move this node to a new parent.
+   *
+   * @param newParent - The new parent node (undefined for root)
+   * @param index - Optional position among siblings
+   */
+  move(newParent, index) {
+    const node = this[INTERNAL_SYMBOL].getNode();
+    const parentNode = newParent ? newParent[INTERNAL_SYMBOL].getNode() : void 0;
+    node.move?.(parentNode, index);
+    this[INTERNAL_SYMBOL].commitIfAuto();
+  }
+  /**
+   * Move this node to be after the given sibling.
+   */
+  moveAfter(sibling) {
+    const node = this[INTERNAL_SYMBOL].getNode();
+    const siblingNode = sibling[INTERNAL_SYMBOL].getNode();
+    node.moveAfter(siblingNode);
+    this[INTERNAL_SYMBOL].commitIfAuto();
+  }
+  /**
+   * Move this node to be before the given sibling.
+   */
+  moveBefore(sibling) {
+    const node = this[INTERNAL_SYMBOL].getNode();
+    const siblingNode = sibling[INTERNAL_SYMBOL].getNode();
+    node.moveBefore(siblingNode);
+    this[INTERNAL_SYMBOL].commitIfAuto();
+  }
+  /**
+   * Get the index of this node among its siblings.
+   */
+  index() {
+    const node = this[INTERNAL_SYMBOL].getNode();
+    return node.index();
+  }
+  /**
+   * Get the fractional index string for ordering.
+   */
+  fractionalIndex() {
+    const node = this[INTERNAL_SYMBOL].getNode();
+    return node.fractionalIndex();
+  }
+  /**
+   * Check if this node has been deleted.
+   */
+  isDeleted() {
+    const node = this[INTERNAL_SYMBOL].getNode();
+    return node.isDeleted();
+  }
+  /**
+   * Serialize this node and its descendants to JSON.
+   */
+  toJSON() {
+    const children = this.children();
+    return {
+      id: this.id,
+      parent: this.parent()?.id ?? null,
+      index: this.index() ?? 0,
+      fractionalIndex: this.fractionalIndex() ?? "",
+      data: this.data.toJSON(),
+      children: children.map((child) => child.toJSON())
+    };
+  }
+};
+
+// src/typed-refs/tree-ref-internals.ts
+var TreeRefInternals = class extends BaseRefInternals {
+  nodeCache = /* @__PURE__ */ new Map();
+  treeRef = null;
+  /** Set the parent TreeRef (needed for creating node refs) */
+  setTreeRef(treeRef) {
+    this.treeRef = treeRef;
+  }
+  /** Get the data shape for tree nodes */
+  getDataShape() {
+    const shape = this.getShape();
+    return shape.shape;
+  }
+  /** Get or create a node ref for a LoroTreeNode */
+  getOrCreateNodeRef(node) {
+    const id = node.id;
+    if (!this.treeRef) {
+      throw new Error("treeRef required");
+    }
+    let nodeRef = this.nodeCache.get(id);
+    if (!nodeRef) {
+      nodeRef = new TreeNodeRef({
+        node,
+        dataShape: this.getDataShape(),
+        treeRef: this.treeRef,
+        autoCommit: this.getAutoCommit(),
+        batchedMutation: this.getBatchedMutation(),
+        getDoc: () => this.getDoc()
+      });
+      this.nodeCache.set(id, nodeRef);
+    }
+    return nodeRef;
+  }
+  /** Get a node by its ID */
+  getNodeByID(id) {
+    const cached = this.nodeCache.get(id);
+    if (cached) return cached;
+    const container = this.getContainer();
+    if (!container.has(id)) return void 0;
+    const nodes = container.nodes();
+    const node = nodes.find((n) => n.id === id);
+    if (!node) return void 0;
+    return this.getOrCreateNodeRef(node);
+  }
+  /** Delete a node from the tree */
+  delete(target) {
+    const id = typeof target === "string" ? target : target.id;
+    const container = this.getContainer();
+    container.delete(id);
+    this.nodeCache.delete(id);
     this.commitIfAuto();
   }
-  get length() {
-    return this.container.length;
+  /** Absorb mutated plain values back into Loro containers */
+  absorbPlainValues() {
+    for (const nodeRef of this.nodeCache.values()) {
+      nodeRef[INTERNAL_SYMBOL].absorbPlainValues();
+    }
+  }
+  /** Create the loro namespace for tree */
+  createLoroNamespace() {
+    const self = this;
+    return {
+      get doc() {
+        return self.getDoc();
+      },
+      get container() {
+        return self.getContainer();
+      },
+      subscribe(callback) {
+        return self.getContainer().subscribe(callback);
+      }
+    };
   }
 };
 
-// src/typed-refs/tree.ts
+// src/typed-refs/tree-ref.ts
 var TreeRef = class extends TypedRef {
-  absorbPlainValues() {
+  [INTERNAL_SYMBOL];
+  constructor(params) {
+    super();
+    this[INTERNAL_SYMBOL] = new TreeRefInternals(params);
+    this[INTERNAL_SYMBOL].setTreeRef(this);
   }
-  toJSON() {
-    return this.container.toJSON();
+  /**
+   * Get the data shape for tree nodes.
+   */
+  get dataShape() {
+    return this[INTERNAL_SYMBOL].getDataShape();
   }
-  createNode(parent, index) {
-    this.assertMutable();
-    return this.container.createNode(parent, index);
+  /**
+   * Get or create a node ref for a LoroTreeNode.
+   */
+  getOrCreateNodeRef(node) {
+    return this[INTERNAL_SYMBOL].getOrCreateNodeRef(node);
   }
-  move(target, parent, index) {
-    this.assertMutable();
-    this.container.move(target, parent, index);
+  /**
+   * Get a node by its ID.
+   */
+  getNodeByID(id) {
+    return this[INTERNAL_SYMBOL].getNodeByID(id);
   }
+  /**
+   * Delete a node from the tree.
+   */
   delete(target) {
-    this.assertMutable();
-    this.container.delete(target);
+    this[INTERNAL_SYMBOL].delete(target);
   }
-  has(target) {
-    return this.container.has(target);
+  /**
+   * Serialize the tree to a nested JSON structure.
+   * Each node includes its data and children recursively.
+   */
+  toJSON() {
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    const nativeJson = container.toJSON();
+    return this.transformNativeJson(nativeJson);
   }
-  getNodeByID(id) {
-    return this.container.getNodeByID ? this.container.getNodeByID(id) : void 0;
+  /**
+   * Create a new root node with optional initial data.
+   *
+   * @param initialData - Optional partial data to initialize the node with
+   * @returns The created TreeNodeRef
+   */
+  createNode(initialData) {
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    const loroNode = container.createNode();
+    const nodeRef = this.getOrCreateNodeRef(loroNode);
+    if (initialData) {
+      for (const [key, value] of Object.entries(initialData)) {
+        ;
+        nodeRef.data[key] = value;
+      }
+    }
+    this[INTERNAL_SYMBOL].commitIfAuto();
+    return nodeRef;
+  }
+  /**
+   * Get all root nodes (nodes without parents).
+   * Returns nodes in their fractional index order.
+   */
+  roots() {
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.roots().map((node) => this.getOrCreateNodeRef(node));
+  }
+  /**
+   * Get all nodes in the tree (unordered).
+   * Includes all nodes, not just roots.
+   */
+  nodes() {
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.nodes().map((node) => this.getOrCreateNodeRef(node));
+  }
+  /**
+   * Check if a node with the given ID exists in the tree.
+   */
+  has(id) {
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    return container.has(id);
+  }
+  /**
+   * Enable fractional index generation for ordering.
+   *
+   * @param jitter - Optional jitter value to avoid conflicts (0 = no jitter)
+   */
+  enableFractionalIndex(jitter = 0) {
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    container.enableFractionalIndex(jitter);
+  }
+  /**
+   * Transform Loro's native JSON format to our typed format.
+   */
+  transformNativeJson(nodes) {
+    return nodes.map((node) => ({
+      id: node.id,
+      parent: node.parent,
+      index: node.index,
+      fractionalIndex: node.fractional_index,
+      data: node.meta,
+      children: this.transformNativeJson(node.children || [])
+    }));
+  }
+  /**
+   * Get a flat array representation of all nodes.
+   * Flattens the nested tree structure into a single array.
+   */
+  toArray() {
+    const result = [];
+    const flattenNodes = (nodes) => {
+      for (const node of nodes) {
+        result.push({
+          id: node.id,
+          parent: node.parent,
+          index: node.index,
+          fractionalIndex: node.fractional_index,
+          data: node.meta
+        });
+        if (node.children && node.children.length > 0) {
+          flattenNodes(node.children);
+        }
+      }
+    };
+    const container = this[INTERNAL_SYMBOL].getContainer();
+    const nativeJson = container.toJSON();
+    flattenNodes(nativeJson);
+    return result;
   }
 };
 
@@ -2086,20 +2861,14 @@ var containerConstructor = {
 function hasContainerConstructor(type) {
   return type in containerConstructor;
 }
-function unwrapReadonlyPrimitive(ref, shape) {
-  if (shape._type === "counter") {
-    return ref.value;
-  }
-  if (shape._type === "text") {
-    return ref.toString();
-  }
-  return ref;
+function hasInternalSymbol(value) {
+  return value !== null && typeof value === "object" && INTERNAL_SYMBOL in value;
 }
 function absorbCachedPlainValues(cache, getContainer) {
   let container;
   for (const [key, ref] of cache.entries()) {
-    if (ref instanceof TypedRef) {
-      ref.absorbPlainValues();
+    if (hasInternalSymbol(ref)) {
+      ref[INTERNAL_SYMBOL].absorbPlainValues();
     } else {
       if (!container) container = getContainer();
       container.set(key, ref);
@@ -2128,7 +2897,9 @@ function createContainerTypedRef(params) {
         listProxyHandler
       );
     case "struct":
-      return new StructRef(params);
+      return createStructRef(
+        params
+      );
     case "movableList":
       return new Proxy(
         new MovableListRef(params),
@@ -2141,8 +2912,16 @@ function createContainerTypedRef(params) {
       );
     case "text":
       return new TextRef(params);
-    case "tree":
-      return new TreeRef(params);
+    case "tree": {
+      const treeShape = params.shape;
+      return new TreeRef({
+        shape: treeShape,
+        placeholder: params.placeholder,
+        getContainer: params.getContainer,
+        autoCommit: params.autoCommit,
+        getDoc: params.getDoc
+      });
+    }
     default:
       throw new Error(
         `Unknown container type: ${params.shape._type}`
@@ -2150,7 +2929,8 @@ function createContainerTypedRef(params) {
   }
 }
 function assignPlainValueToTypedRef(ref, value) {
-  const shapeType = ref.shape._type;
+  const shape = ref[INTERNAL_SYMBOL]?.getShape?.() ?? ref.shape;
+  const shapeType = shape?._type;
   if (shapeType === "struct" || shapeType === "record") {
     for (const k in value) {
       ;
@@ -2196,7 +2976,7 @@ function assignPlainValueToTypedRef(ref, value) {
   return false;
 }
 
-// src/typed-refs/doc.ts
+// src/typed-refs/doc-ref-internals.ts
 var containerGetter = {
   counter: "getCounter",
   list: "getList",
@@ -2207,23 +2987,22 @@ var containerGetter = {
   text: "getText",
   tree: "getTree"
 };
-var DocRef = class extends TypedRef {
-  _doc;
+var DocRefInternals = class extends BaseRefInternals {
   propertyCache = /* @__PURE__ */ new Map();
+  doc;
   requiredPlaceholder;
-  constructor(_params) {
+  constructor(params) {
     super({
-      ..._params,
+      ...params,
       getContainer: () => {
         throw new Error("can't get container on DocRef");
       },
-      getDoc: () => this._doc
+      getDoc: () => params.doc
     });
-    if (!_params.placeholder) throw new Error("placeholder required");
-    this._doc = _params.doc;
-    this.requiredPlaceholder = _params.placeholder;
-    this.createLazyProperties();
+    this.doc = params.doc;
+    this.requiredPlaceholder = params.placeholder;
   }
+  /** Get typed ref params for creating child refs at a key */
   getTypedRefParams(key, shape) {
     if (shape._type === "any") {
       throw new Error(
@@ -2231,53 +3010,59 @@ var DocRef = class extends TypedRef {
       );
     }
     const getterName = containerGetter[shape._type];
-    const getter = this._doc[getterName].bind(this._doc);
+    const getter = this.doc[getterName].bind(this.doc);
     return {
       shape,
       placeholder: this.requiredPlaceholder[key],
       getContainer: () => getter(key),
-      readonly: this.readonly,
-      autoCommit: this._params.autoCommit,
-      getDoc: () => this._doc
+      autoCommit: this.getAutoCommit(),
+      batchedMutation: this.getBatchedMutation(),
+      getDoc: () => this.doc
     };
   }
+  /** Get or create a typed ref for a key */
   getOrCreateTypedRef(key, shape) {
-    if (this.readonly && (shape._type === "counter" || shape._type === "text")) {
-      const shallow = this._doc.getShallowValue();
-      if (!shallow[key]) {
-        return this.requiredPlaceholder[key];
-      }
-    }
     let ref = this.propertyCache.get(key);
     if (!ref) {
       ref = createContainerTypedRef(this.getTypedRefParams(key, shape));
       this.propertyCache.set(key, ref);
     }
-    if (this.readonly) {
-      return unwrapReadonlyPrimitive(ref, shape);
-    }
     return ref;
   }
+  /** Absorb mutated plain values back into Loro containers */
+  absorbPlainValues() {
+    for (const [, ref] of this.propertyCache.entries()) {
+      ref[INTERNAL_SYMBOL].absorbPlainValues();
+    }
+  }
+};
+
+// src/typed-refs/doc-ref.ts
+var DocRef = class extends TypedRef {
+  [INTERNAL_SYMBOL];
+  constructor(params) {
+    super();
+    if (!params.placeholder) throw new Error("placeholder required");
+    this[INTERNAL_SYMBOL] = new DocRefInternals(params);
+    this.createLazyProperties();
+  }
   createLazyProperties() {
-    for (const key in this.shape.shapes) {
-      const shape = this.shape.shapes[key];
+    const shape = this[INTERNAL_SYMBOL].getShape();
+    for (const key in shape.shapes) {
+      const containerShape = shape.shapes[key];
       Object.defineProperty(this, key, {
-        get: () => this.getOrCreateTypedRef(key, shape),
+        get: () => this[INTERNAL_SYMBOL].getOrCreateTypedRef(key, containerShape),
         enumerable: true
       });
     }
   }
   toJSON() {
+    const shape = this[INTERNAL_SYMBOL].getShape();
     return serializeRefToJSON(
       this,
-      Object.keys(this.shape.shapes)
+      Object.keys(shape.shapes)
     );
   }
-  absorbPlainValues() {
-    for (const [, ref] of this.propertyCache.entries()) {
-      ref.absorbPlainValues();
-    }
-  }
 };
 
 // src/validation.ts
@@ -2509,68 +3294,11 @@ function validatePlaceholder(placeholder, schema) {
 }
 
 // src/typed-doc.ts
-var TypedDocMeta = class {
-  constructor(internal) {
-    this.internal = internal;
-  }
-  /**
-   * The primary method of mutating typed documents.
-   * Batches multiple mutations into a single transaction.
-   * All changes commit together at the end.
-   *
-   * Use this for:
-   * - Find-and-mutate operations (required due to JS limitations)
-   * - Performance (fewer commits)
-   * - Atomic undo (all changes = one undo step)
-   *
-   * Returns the doc for chaining.
-   */
-  change(fn) {
-    this.internal.change(fn);
-    return this.internal.proxy;
-  }
-  /**
-   * Returns the full plain JavaScript object representation of the document.
-   * This is an expensive O(N) operation that serializes the entire document.
-   */
-  toJSON() {
-    return this.internal.toJSON();
-  }
-  /**
-   * Apply JSON Patch operations to the document
-   *
-   * @param patch - Array of JSON Patch operations (RFC 6902)
-   * @param pathPrefix - Optional path prefix for scoped operations
-   * @returns Updated document value
-   */
-  applyPatch(patch, pathPrefix) {
-    this.internal.applyPatch(patch, pathPrefix);
-    return this.internal.proxy;
-  }
-  /**
-   * Access the underlying LoroDoc for advanced operations.
-   */
-  get loroDoc() {
-    return this.internal.loroDoc;
-  }
-  /**
-   * Access the document schema shape.
-   */
-  get docShape() {
-    return this.internal.docShape;
-  }
-  /**
-   * Get raw CRDT value without placeholder overlay.
-   */
-  get rawValue() {
-    return this.internal.rawValue;
-  }
-};
 var TypedDocInternal = class {
   shape;
   placeholder;
   doc;
-  _valueRef = null;
+  valueRef = null;
   // Reference to the proxy for returning from change()
   proxy = null;
   constructor(shape, doc = new LoroDoc()) {
@@ -2580,15 +3308,15 @@ var TypedDocInternal = class {
     validatePlaceholder(this.placeholder, this.shape);
   }
   get value() {
-    if (!this._valueRef) {
-      this._valueRef = new DocRef({
+    if (!this.valueRef) {
+      this.valueRef = new DocRef({
         shape: this.shape,
         placeholder: this.placeholder,
         doc: this.doc,
         autoCommit: true
       });
     }
-    return this._valueRef;
+    return this.valueRef;
   }
   toJSON() {
     const crdtValue = this.doc.toJSON();
@@ -2603,12 +3331,14 @@ var TypedDocInternal = class {
       shape: this.shape,
       placeholder: this.placeholder,
       doc: this.doc,
-      autoCommit: false
+      autoCommit: false,
+      batchedMutation: true
+      // Enable value shape caching for find-and-mutate patterns
     });
     fn(draft);
-    draft.absorbPlainValues();
+    draft[INTERNAL_SYMBOL].absorbPlainValues();
     this.doc.commit();
-    this._valueRef = null;
+    this.valueRef = null;
   }
   applyPatch(patch, pathPrefix) {
     this.change((draft) => {
@@ -2632,11 +3362,37 @@ var TypedDocInternal = class {
 };
 function createTypedDoc(shape, existingDoc) {
   const internal = new TypedDocInternal(shape, existingDoc || new LoroDoc());
-  const meta = new TypedDocMeta(internal);
+  const loroNamespace = {
+    get doc() {
+      return internal.loroDoc;
+    },
+    get container() {
+      return internal.loroDoc;
+    },
+    subscribe(callback) {
+      return internal.loroDoc.subscribe(callback);
+    },
+    applyPatch(patch, pathPrefix) {
+      internal.applyPatch(patch, pathPrefix);
+    },
+    get docShape() {
+      return internal.docShape;
+    },
+    get rawValue() {
+      return internal.rawValue;
+    }
+  };
+  const changeFunction = (fn) => {
+    internal.change(fn);
+    return proxy;
+  };
   const proxy = new Proxy(internal.value, {
     get(target, prop, receiver) {
-      if (prop === "$") {
-        return meta;
+      if (prop === LORO_SYMBOL) {
+        return loroNamespace;
+      }
+      if (prop === "change") {
+        return changeFunction;
       }
       if (prop === "toJSON") {
         return () => internal.toJSON();
@@ -2644,26 +3400,33 @@ function createTypedDoc(shape, existingDoc) {
       return Reflect.get(target, prop, receiver);
     },
     set(target, prop, value, receiver) {
-      if (prop === "$") {
+      if (prop === LORO_SYMBOL || prop === "change") {
         return false;
       }
       return Reflect.set(target, prop, value, receiver);
     },
     // Support 'in' operator
     has(target, prop) {
-      if (prop === "$") return true;
+      if (prop === LORO_SYMBOL || prop === "change") return true;
       return Reflect.has(target, prop);
     },
-    // Support Object.keys() - don't include $ in enumeration
+    // Support Object.keys() - don't include change or LORO_SYMBOL in enumeration
     ownKeys(target) {
       return Reflect.ownKeys(target);
     },
     getOwnPropertyDescriptor(target, prop) {
-      if (prop === "$") {
+      if (prop === "change") {
+        return {
+          configurable: true,
+          enumerable: false,
+          value: changeFunction
+        };
+      }
+      if (prop === LORO_SYMBOL) {
         return {
           configurable: true,
           enumerable: false,
-          value: meta
+          value: loroNamespace
         };
       }
       return Reflect.getOwnPropertyDescriptor(target, prop);
@@ -2673,6 +3436,7 @@ function createTypedDoc(shape, existingDoc) {
   return proxy;
 }
 export {
+  LORO_SYMBOL,
   Shape,
   change,
   compileToJsonPath,
@@ -2683,8 +3447,10 @@ export {
   deriveShapePlaceholder,
   evaluatePath,
   evaluatePathOnValue,
+  getLoroContainer,
   getLoroDoc,
   hasWildcard,
+  loro,
   mergeValue,
   overlayPlaceholder,
   validatePlaceholder