@loro-extended/change 4.0.0 → 5.0.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LoroDoc, LoroCounter, LoroList, LoroMovableList, Container, LoroMap, Value, LoroText, TreeID, LoroTree } from 'loro-crdt';
+import { LoroDoc, Container, LoroTreeNode, TreeID, Subscription, LoroText, LoroList, LoroMovableList, LoroMap, LoroCounter, LoroTree, Value } from 'loro-crdt';
 
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 /**
@@ -71,181 +71,911 @@ type InferPlaceholderType<T> = T extends Shape<any, any, infer P> ? P : never;
  */
 type Mutable<T extends DocShape<Record<string, ContainerShape>>> = InferMutableType<T>;
 
+/** biome-ignore-all lint/suspicious/noExplicitAny: JSON Patch values can be any type */
+
+type JsonPatchAddOperation = {
+    op: "add";
+    path: string | (string | number)[];
+    value: any;
+};
+type JsonPatchRemoveOperation = {
+    op: "remove";
+    path: string | (string | number)[];
+};
+type JsonPatchReplaceOperation = {
+    op: "replace";
+    path: string | (string | number)[];
+    value: any;
+};
+type JsonPatchMoveOperation = {
+    op: "move";
+    path: string | (string | number)[];
+    from: string | (string | number)[];
+};
+type JsonPatchCopyOperation = {
+    op: "copy";
+    path: string | (string | number)[];
+    from: string | (string | number)[];
+};
+type JsonPatchTestOperation = {
+    op: "test";
+    path: string | (string | number)[];
+    value: any;
+};
+type JsonPatchOperation = JsonPatchAddOperation | JsonPatchRemoveOperation | JsonPatchReplaceOperation | JsonPatchMoveOperation | JsonPatchCopyOperation | JsonPatchTestOperation;
+type JsonPatch = JsonPatchOperation[];
+
+/** biome-ignore-all lint/suspicious/noExplicitAny: fix later */
+
+/**
+ * The proxied TypedDoc type that provides direct schema access.
+ * Schema properties are accessed directly on the doc object.
+ *
+ * @example
+ * ```typescript
+ * const doc = createTypedDoc(schema);
+ *
+ * // Direct schema access
+ * doc.count.increment(5);
+ * doc.title.insert(0, "Hello");
+ *
+ * // Serialize to JSON (works on doc and all refs)
+ * const snapshot = doc.toJSON();
+ * const users = doc.users.toJSON();
+ *
+ * // Batched mutations via change()
+ * doc.change(draft => {
+ *   draft.count.increment(10);
+ *   draft.title.update("World");
+ * });
+ *
+ * // Access CRDT internals via loro()
+ * import { loro } from "@loro-extended/change";
+ * loro(doc).doc;  // LoroDoc
+ * loro(doc).subscribe(callback);
+ * ```
+ */
+type TypedDoc<Shape extends DocShape> = Mutable<Shape> & {
+    /**
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * doc.change(draft => {
+     *   draft.count.increment(10);
+     *   draft.title.update("World");
+     * });
+     * ```
+     */
+    change(fn: (draft: Mutable<Shape>) => void): TypedDoc<Shape>;
+    /**
+     * Returns the full plain JavaScript object representation of the document.
+     * This is an O(N) operation that serializes the entire document.
+     *
+     * @example
+     * ```typescript
+     * const snapshot = doc.toJSON();
+     * console.log(snapshot.count); // number
+     * ```
+     */
+    toJSON(): Infer<Shape>;
+};
+/**
+ * Creates a new TypedDoc with the given schema.
+ * Returns a proxied document where schema properties are accessed directly.
+ *
+ * @param shape - The document schema (with optional .placeholder() values)
+ * @param existingDoc - Optional existing LoroDoc to wrap
+ * @returns A proxied TypedDoc with direct schema access
+ *
+ * @example
+ * ```typescript
+ * const schema = Shape.doc({
+ *   title: Shape.text(),
+ *   count: Shape.counter(),
+ * });
+ *
+ * const doc = createTypedDoc(schema);
+ *
+ * // Direct mutations (auto-commit)
+ * doc.count.increment(5);
+ * doc.title.insert(0, "Hello");
+ *
+ * // Batched mutations via change()
+ * doc.change(draft => {
+ *   draft.count.increment(10);
+ *   draft.title.update("World");
+ * });
+ *
+ * // Get plain JSON
+ * const snapshot = doc.toJSON();
+ *
+ * // Access CRDT internals via loro()
+ * import { loro } from "@loro-extended/change";
+ * loro(doc).doc;  // LoroDoc
+ * loro(doc).subscribe(callback);
+ * ```
+ */
+declare function createTypedDoc<Shape extends DocShape>(shape: Shape, existingDoc?: LoroDoc): TypedDoc<Shape>;
+
+/**
+ * Internal implementation for ListRefBase.
+ * Contains all logic, state, and implementation details for list operations.
+ */
+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>;
+    /** Get item for predicate functions (returns plain value) */
+    getPredicateItem(index: number): Item | undefined;
+    /** Get mutable item for return values (returns ref or cached value) */
+    getMutableItem(index: number): MutableItem | undefined;
+    /** Insert with automatic conversion */
+    insertWithConversion(index: number, item: unknown): void;
+    /** Push with automatic conversion */
+    pushWithConversion(item: unknown): void;
+    /** Absorb value at specific index (for value shapes) - subclasses override */
+    absorbValueAtIndex(_index: number, _value: unknown): void;
+    /** Update cache indices after a delete operation */
+    updateCacheForDelete(deleteIndex: number, deleteLen: number): void;
+    /** Update cache indices after an insert operation */
+    updateCacheForInsert(insertIndex: number): void;
+    /** Absorb mutated plain values back into Loro containers */
+    absorbPlainValues(): void;
+    /** Create the loro namespace for list */
+    protected createLoroNamespace(): LoroListRef;
+}
+/**
+ * Shared logic for list operations - thin facade that delegates to ListRefBaseInternals.
+ */
+declare abstract class ListRefBase<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"], MutableItem = NestedShape["_mutable"]> extends TypedRef<any> {
+    [INTERNAL_SYMBOL]: ListRefBaseInternals<NestedShape, Item, MutableItem>;
+    constructor(params: TypedRefParams<any>);
+    /** Subclasses override to create their specific internals */
+    protected abstract createInternals(params: TypedRefParams<any>): ListRefBaseInternals<NestedShape, Item, MutableItem>;
+    find(predicate: (item: Item, index: number) => boolean): MutableItem | undefined;
+    findIndex(predicate: (item: Item, index: number) => boolean): number;
+    map<ReturnType>(callback: (item: Item, index: number) => ReturnType): ReturnType[];
+    filter(predicate: (item: Item, index: number) => boolean): MutableItem[];
+    forEach(callback: (item: Item, index: number) => void): void;
+    some(predicate: (item: Item, index: number) => boolean): boolean;
+    every(predicate: (item: Item, index: number) => boolean): boolean;
+    slice(start?: number, end?: number): MutableItem[];
+    insert(index: number, item: Item): void;
+    delete(index: number, len: number): void;
+    push(item: Item): void;
+    pushContainer(container: Container): Container;
+    insertContainer(index: number, container: Container): Container;
+    get(index: number): MutableItem | undefined;
+    toArray(): Item[];
+    toJSON(): Item[];
+    [Symbol.iterator](): IterableIterator<MutableItem>;
+    get length(): number;
+}
+
+/**
+ * Internal implementation for ListRef.
+ * Extends ListRefBaseInternals with LoroList-specific absorption logic.
+ */
+declare class ListRefInternals<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"], MutableItem = NestedShape["_mutable"]> extends ListRefBaseInternals<NestedShape, Item, MutableItem> {
+    /** Absorb value at specific index for LoroList */
+    absorbValueAtIndex(index: number, value: unknown): void;
+}
+
+/**
+ * List typed ref - thin facade that delegates to ListRefInternals.
+ */
+declare class ListRef<NestedShape extends ContainerOrValueShape> extends ListRefBase<NestedShape> {
+    [index: number]: InferMutableType<NestedShape> | undefined;
+    protected createInternals(params: TypedRefParams<any>): ListRefInternals<NestedShape>;
+}
+
+/**
+ * Internal implementation for MovableListRef.
+ * Extends ListRefBaseInternals with LoroMovableList-specific methods.
+ */
+declare class MovableListRefInternals<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"], MutableItem = NestedShape["_mutable"]> extends ListRefBaseInternals<NestedShape, Item, MutableItem> {
+    /** Absorb value at specific index for LoroMovableList */
+    absorbValueAtIndex(index: number, value: unknown): void;
+    /** Move an item from one index to another */
+    move(from: number, to: number): void;
+    /** Set an item at a specific index */
+    set(index: number, item: unknown): void;
+}
+
+/**
+ * Movable list typed ref - thin facade that delegates to MovableListRefInternals.
+ */
+declare class MovableListRef<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"]> extends ListRefBase<NestedShape> {
+    [INTERNAL_SYMBOL]: MovableListRefInternals<NestedShape>;
+    [index: number]: InferMutableType<NestedShape> | undefined;
+    protected createInternals(params: TypedRefParams<any>): MovableListRefInternals<NestedShape>;
+    move(from: number, to: number): void;
+    set(index: number, item: Exclude<Item, Container>): void;
+}
+
+/**
+ * Internal implementation for RecordRef.
+ * Contains all logic, state, and implementation details.
+ */
+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>;
+    /** 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) */
+    getOrCreateRef(key: string): unknown;
+    /** Set a value at a key */
+    set(key: string, value: any): void;
+    /** Delete a key */
+    delete(key: string): void;
+    /** Absorb mutated plain values back into Loro containers */
+    absorbPlainValues(): void;
+    /** Create the loro namespace for record */
+    protected createLoroNamespace(): LoroMapRef;
+}
+
+/**
+ * Record typed ref - thin facade that delegates to RecordRefInternals.
+ */
+declare class RecordRef<NestedShape extends ContainerOrValueShape> extends TypedRef<any> {
+    [key: string]: InferMutableType<NestedShape> | undefined | any;
+    [INTERNAL_SYMBOL]: RecordRefInternals<NestedShape>;
+    constructor(params: TypedRefParams<any>);
+    /** Set a value at a key */
+    set(key: string, value: any): void;
+    /** Delete a key */
+    delete(key: string): void;
+    get(key: string): InferMutableType<NestedShape> | undefined;
+    setContainer<C extends Container>(key: string, container: C): C;
+    has(key: string): boolean;
+    keys(): string[];
+    values(): any[];
+    get size(): number;
+    toJSON(): Record<string, Infer<NestedShape>>;
+}
+
+/**
+ * Typed ref for struct containers (objects with fixed keys).
+ * Uses LoroMap as the underlying container.
+ *
+ * Supports JavaScript-native object behavior:
+ * - Property access: obj.key
+ * - Property assignment: obj.key = value
+ * - Object.keys(obj)
+ * - 'key' in obj
+ * - delete obj.key
+ *
+ * @example
+ * ```typescript
+ * const schema = Shape.doc({
+ *   settings: Shape.struct({
+ *     darkMode: Shape.plain.boolean().placeholder(false),
+ *     fontSize: Shape.plain.number().placeholder(14),
+ *   }),
+ * });
+ *
+ * const doc = createTypedDoc(schema);
+ *
+ * // Property access
+ * doc.settings.darkMode = true;
+ * console.log(doc.settings.darkMode); // true
+ *
+ * // Object.keys()
+ * console.log(Object.keys(doc.settings)); // ['darkMode', 'fontSize']
+ *
+ * // 'key' in obj
+ * console.log('darkMode' in doc.settings); // true
+ *
+ * // delete obj.key
+ * delete doc.settings.darkMode;
+ *
+ * // CRDT access via loro()
+ * import { loro } from "@loro-extended/change";
+ * loro(doc.settings).setContainer('nested', loroMap);
+ * loro(doc.settings).subscribe(callback);
+ * ```
+ */
+type StructRef<NestedShapes extends Record<string, ContainerOrValueShape>> = {
+    [K in keyof NestedShapes]: NestedShapes[K]["_mutable"];
+} & {
+    /**
+     * Serializes the struct to a plain JSON-compatible object.
+     */
+    toJSON(): Infer<StructContainerShape<NestedShapes>>;
+    /**
+     * Internal methods accessed via INTERNAL_SYMBOL.
+     * @internal
+     */
+    [INTERNAL_SYMBOL]: RefInternalsBase;
+};
+
+/**
+ * Internal implementation for TextRef.
+ * Contains all logic, state, and implementation details.
+ */
+declare class TextRefInternals extends BaseRefInternals<TextContainerShape> {
+    private materialized;
+    /** Insert text at the given index */
+    insert(index: number, content: string): void;
+    /** Delete text at the given index */
+    delete(index: number, len: number): void;
+    /** Update the entire text content */
+    update(text: string): void;
+    /** Mark a range of text with a key-value pair */
+    mark(range: {
+        start: number;
+        end: number;
+    }, key: string, value: any): void;
+    /** Remove a mark from a range of text */
+    unmark(range: {
+        start: number;
+        end: number;
+    }, key: string): void;
+    /** Apply a delta to the text */
+    applyDelta(delta: any[]): void;
+    /** Get the text as a string */
+    getStringValue(): string;
+    /** Get the text as a delta */
+    toDelta(): any[];
+    /** Get the length of the text */
+    getLength(): number;
+    /** No plain values in text */
+    absorbPlainValues(): void;
+    /** Create the loro namespace for text */
+    protected createLoroNamespace(): LoroTextRef;
+}
+
+/**
+ * Text typed ref - thin facade that delegates to TextRefInternals.
+ */
+declare class TextRef extends TypedRef<TextContainerShape> {
+    [INTERNAL_SYMBOL]: TextRefInternals;
+    constructor(params: TypedRefParams<TextContainerShape>);
+    /** Insert text at the given index */
+    insert(index: number, content: string): void;
+    /** Delete text at the given index */
+    delete(index: number, len: number): void;
+    /** Update the entire text content */
+    update(text: string): void;
+    /** Mark a range of text with a key-value pair */
+    mark(range: {
+        start: number;
+        end: number;
+    }, key: string, value: any): void;
+    /** Remove a mark from a range of text */
+    unmark(range: {
+        start: number;
+        end: number;
+    }, key: string): void;
+    /** Apply a delta to the text */
+    applyDelta(delta: any[]): void;
+    /** Get the text as a string */
+    toString(): string;
+    valueOf(): string;
+    toJSON(): string;
+    [Symbol.toPrimitive](_hint: string): string;
+    /** Get the text as a delta */
+    toDelta(): any[];
+    /** Get the length of the text */
+    get length(): number;
+}
+
+interface TreeRefLike<DataShape extends StructContainerShape> {
+    getOrCreateNodeRef(node: LoroTreeNode): TreeNodeRef<DataShape>;
+}
+/**
+ * Internal implementation for TreeNodeRef.
+ * Contains all logic, state, and implementation details.
+ */
+declare class TreeNodeRefInternals<DataShape extends StructContainerShape> implements RefInternalsBase {
+    private readonly params;
+    private dataRef;
+    constructor(params: TreeNodeRefParams<DataShape>);
+    /** Get the underlying LoroTreeNode */
+    getNode(): LoroTreeNode;
+    /** Get the data shape for this node */
+    getDataShape(): DataShape;
+    /** Get the parent TreeRef */
+    getTreeRef(): TreeRefLike<DataShape>;
+    /** Check if autoCommit is enabled */
+    getAutoCommit(): boolean;
+    /** Check if in batched mutation mode */
+    getBatchedMutation(): boolean;
+    /** Get the LoroDoc */
+    getDoc(): LoroDoc;
+    /** Commit changes if autoCommit is enabled */
+    commitIfAuto(): void;
+    /** Get or create the data StructRef */
+    getOrCreateDataRef(): StructRef<DataShape["shapes"]>;
+    /** Absorb mutated plain values back into Loro containers */
+    absorbPlainValues(): void;
+}
+
+interface TreeNodeRefParams<DataShape extends StructContainerShape> {
+    node: LoroTreeNode;
+    dataShape: DataShape;
+    treeRef: TreeRefLike<DataShape>;
+    autoCommit?: boolean;
+    batchedMutation?: boolean;
+    getDoc: () => LoroDoc;
+}
+/**
+ * Typed ref for a single tree node - thin facade that delegates to TreeNodeRefInternals.
+ * Provides type-safe access to node metadata via the `.data` property.
+ *
+ * **Note:** TreeNodeRef is not a subclass of TypedRef, but it implements
+ * `[INTERNAL_SYMBOL]: RefInternalsBase` for consistency with other refs.
+ * This allows internal code to call `absorbPlainValues()` uniformly
+ * across all ref types during the `change()` commit phase.
+ *
+ * @example
+ * ```typescript
+ * const node = tree.createNode({ name: "idle", facts: {} })
+ * node.data.name = "active"  // Typed access
+ * const child = node.createNode({ name: "running", facts: {} })
+ * ```
+ */
+declare class TreeNodeRef<DataShape extends StructContainerShape> {
+    [INTERNAL_SYMBOL]: TreeNodeRefInternals<DataShape>;
+    constructor(params: TreeNodeRefParams<DataShape>);
+    /**
+     * The unique TreeID of this node.
+     */
+    get id(): TreeID;
+    /**
+     * Typed access to the node's metadata.
+     * This is a StructRef wrapping the node's LoroMap data container.
+     */
+    get data(): StructRef<DataShape["shapes"]> & {
+        [K in keyof DataShape["shapes"]]: DataShape["shapes"][K]["_mutable"];
+    };
+    /**
+     * 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?: Partial<Infer<DataShape>>, index?: number): TreeNodeRef<DataShape>;
+    /**
+     * Get the parent node, if any.
+     */
+    parent(): TreeNodeRef<DataShape> | undefined;
+    /**
+     * Get all child nodes in order.
+     */
+    children(): TreeNodeRef<DataShape>[];
+    /**
+     * Move this node to a new parent.
+     *
+     * @param newParent - The new parent node (undefined for root)
+     * @param index - Optional position among siblings
+     */
+    move(newParent?: TreeNodeRef<DataShape>, index?: number): void;
+    /**
+     * Move this node to be after the given sibling.
+     */
+    moveAfter(sibling: TreeNodeRef<DataShape>): void;
+    /**
+     * Move this node to be before the given sibling.
+     */
+    moveBefore(sibling: TreeNodeRef<DataShape>): void;
+    /**
+     * Get the index of this node among its siblings.
+     */
+    index(): number | undefined;
+    /**
+     * Get the fractional index string for ordering.
+     */
+    fractionalIndex(): string | undefined;
+    /**
+     * Check if this node has been deleted.
+     */
+    isDeleted(): boolean;
+    /**
+     * Serialize this node and its descendants to JSON.
+     */
+    toJSON(): {
+        id: TreeID;
+        parent: TreeID | null;
+        index: number;
+        fractionalIndex: string;
+        data: Infer<DataShape>;
+        children: any[];
+    };
+}
+
+/**
+ * Internal implementation for TreeRef.
+ * Contains all logic, state, and implementation details.
+ */
+declare class TreeRefInternals<DataShape extends StructContainerShape> extends BaseRefInternals<TreeContainerShape<DataShape>> {
+    private nodeCache;
+    private treeRef;
+    /** Set the parent TreeRef (needed for creating node refs) */
+    setTreeRef(treeRef: TreeRef<DataShape>): void;
+    /** Get the data shape for tree nodes */
+    getDataShape(): DataShape;
+    /** Get or create a node ref for a LoroTreeNode */
+    getOrCreateNodeRef(node: LoroTreeNode): TreeNodeRef<DataShape>;
+    /** Get a node by its ID */
+    getNodeByID(id: TreeID): TreeNodeRef<DataShape> | undefined;
+    /** Delete a node from the tree */
+    delete(target: TreeID | TreeNodeRef<DataShape>): void;
+    /** Absorb mutated plain values back into Loro containers */
+    absorbPlainValues(): void;
+    /** Create the loro namespace for tree */
+    protected createLoroNamespace(): LoroTreeRef;
+}
+
+/**
+ * Typed ref for tree (forest) containers - thin facade that delegates to TreeRefInternals.
+ * Wraps LoroTree with type-safe access to node metadata.
+ *
+ * @example
+ * ```typescript
+ * const StateNodeDataShape = Shape.struct({
+ *   name: Shape.text(),
+ *   facts: Shape.record(Shape.plain.any()),
+ * })
+ *
+ * doc.change(draft => {
+ *   const root = draft.states.createNode({ name: "idle", facts: {} })
+ *   const child = root.createNode({ name: "running", facts: {} })
+ *   child.data.name = "active"
+ * })
+ * ```
+ */
+declare class TreeRef<DataShape extends StructContainerShape> extends TypedRef<TreeContainerShape<DataShape>> {
+    [INTERNAL_SYMBOL]: TreeRefInternals<DataShape>;
+    constructor(params: TypedRefParams<TreeContainerShape<DataShape>>);
+    /**
+     * Get the data shape for tree nodes.
+     */
+    private get dataShape();
+    /**
+     * Get or create a node ref for a LoroTreeNode.
+     */
+    getOrCreateNodeRef(node: LoroTreeNode): TreeNodeRef<DataShape>;
+    /**
+     * Get a node by its ID.
+     */
+    getNodeByID(id: TreeID): TreeNodeRef<DataShape> | undefined;
+    /**
+     * Delete a node from the tree.
+     */
+    delete(target: TreeID | TreeNodeRef<DataShape>): void;
+    /**
+     * Serialize the tree to a nested JSON structure.
+     * Each node includes its data and children recursively.
+     */
+    toJSON(): Infer<TreeContainerShape<DataShape>>;
+    /**
+     * 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?: Partial<Infer<DataShape>>): TreeNodeRef<DataShape>;
+    /**
+     * Get all root nodes (nodes without parents).
+     * Returns nodes in their fractional index order.
+     */
+    roots(): TreeNodeRef<DataShape>[];
+    /**
+     * Get all nodes in the tree (unordered).
+     * Includes all nodes, not just roots.
+     */
+    nodes(): TreeNodeRef<DataShape>[];
+    /**
+     * Check if a node with the given ID exists in the tree.
+     */
+    has(id: TreeID): boolean;
+    /**
+     * Enable fractional index generation for ordering.
+     *
+     * @param jitter - Optional jitter value to avoid conflicts (0 = no jitter)
+     */
+    enableFractionalIndex(jitter?: number): void;
+    /**
+     * Transform Loro's native JSON format to our typed format.
+     */
+    private transformNativeJson;
+    /**
+     * Get a flat array representation of all nodes.
+     * Flattens the nested tree structure into a single array.
+     */
+    toArray(): Array<{
+        id: TreeID;
+        parent: TreeID | null;
+        index: number;
+        fractionalIndex: string;
+        data: Infer<DataShape>;
+    }>;
+}
+
+/**
+ * The `loro()` function - single escape hatch for CRDT internals.
+ *
+ * Design Principle:
+ * > If it takes a plain JavaScript value, keep it on the ref.
+ * > If it takes a Loro container or exposes CRDT internals, move to `loro()`.
+ *
+ * @example
+ * ```typescript
+ * import { loro } from "@loro-extended/change"
+ *
+ * // Access underlying LoroDoc
+ * loro(ref).doc
+ *
+ * // Access underlying Loro container (correctly typed)
+ * loro(ref).container  // LoroList, LoroMap, LoroText, etc.
+ *
+ * // Subscribe to changes
+ * loro(ref).subscribe(callback)
+ *
+ * // Container operations
+ * loro(list).pushContainer(loroMap)
+ * loro(struct).setContainer('key', loroMap)
+ * ```
+ */
+
+/**
+ * Well-known Symbol for loro() access.
+ * This is exported so advanced users can access it directly if needed.
+ */
+declare const LORO_SYMBOL: unique symbol;
+/**
+ * Base interface for all loro() return types.
+ * Provides access to the underlying LoroDoc, container, and subscription.
+ */
+interface LoroRefBase {
+    /** The underlying LoroDoc */
+    readonly doc: LoroDoc;
+    /** The underlying Loro container */
+    readonly container: unknown;
+    /**
+     * Subscribe to container-level changes.
+     * @param callback - Function called when the container changes
+     * @returns Subscription that can be used to unsubscribe
+     */
+    subscribe(callback: (event: unknown) => void): Subscription;
+}
+/**
+ * loro() return type for ListRef and MovableListRef.
+ * Provides container operations that take Loro containers.
+ */
+interface LoroListRef extends LoroRefBase {
+    /** The underlying LoroList or LoroMovableList */
+    readonly container: LoroList | LoroMovableList;
+    /**
+     * Push a Loro container to the end of the list.
+     * Use this when you need to add a pre-existing container.
+     */
+    pushContainer(container: Container): Container;
+    /**
+     * Insert a Loro container at the specified index.
+     * Use this when you need to insert a pre-existing container.
+     */
+    insertContainer(index: number, container: Container): Container;
+}
+/**
+ * loro() return type for StructRef and RecordRef.
+ * Provides container operations that take Loro containers.
+ */
+interface LoroMapRef extends LoroRefBase {
+    /** The underlying LoroMap */
+    readonly container: LoroMap;
+    /**
+     * Set a Loro container at the specified key.
+     * Use this when you need to set a pre-existing container.
+     */
+    setContainer(key: string, container: Container): Container;
+}
+/**
+ * loro() return type for TextRef.
+ */
+interface LoroTextRef extends LoroRefBase {
+    /** The underlying LoroText */
+    readonly container: LoroText;
+}
+/**
+ * loro() return type for CounterRef.
+ */
+interface LoroCounterRef extends LoroRefBase {
+    /** The underlying LoroCounter */
+    readonly container: LoroCounter;
+}
+/**
+ * loro() return type for TreeRef.
+ */
+interface LoroTreeRef extends LoroRefBase {
+    /** The underlying LoroTree */
+    readonly container: LoroTree;
+}
+/**
+ * loro() return type for TypedDoc.
+ * Provides access to doc-level operations.
+ */
+interface LoroTypedDocRef extends LoroRefBase {
+    /** The underlying LoroDoc (same as doc for TypedDoc) */
+    readonly container: LoroDoc;
+    /**
+     * Apply JSON Patch operations to the document.
+     * @param patch - Array of JSON Patch operations (RFC 6902)
+     * @param pathPrefix - Optional path prefix for scoped operations
+     */
+    applyPatch(patch: JsonPatch, pathPrefix?: (string | number)[]): void;
+    /** Access the document schema shape */
+    readonly docShape: DocShape;
+    /** Get raw CRDT value without placeholder overlay */
+    readonly rawValue: unknown;
+}
+/**
+ * Access CRDT internals for a ListRef.
+ */
+declare function loro<NestedShape extends ContainerShape>(ref: ListRef<NestedShape>): LoroListRef;
+/**
+ * Access CRDT internals for a MovableListRef.
+ */
+declare function loro<NestedShape extends ContainerShape>(ref: MovableListRef<NestedShape>): LoroListRef;
+/**
+ * Access CRDT internals for a StructRef.
+ */
+declare function loro<NestedShapes extends Record<string, ContainerOrValueShape>>(ref: StructRef<NestedShapes>): LoroMapRef;
+/**
+ * Access CRDT internals for a RecordRef.
+ */
+declare function loro<NestedShape extends ContainerShape>(ref: RecordRef<NestedShape>): LoroMapRef;
+/**
+ * Access CRDT internals for a TextRef.
+ */
+declare function loro(ref: TextRef): LoroTextRef;
+/**
+ * Access CRDT internals for a CounterRef.
+ */
+declare function loro(ref: CounterRef): LoroCounterRef;
+/**
+ * Access CRDT internals for a TreeRef.
+ */
+declare function loro<DataShape extends StructContainerShape>(ref: TreeRef<DataShape>): LoroTreeRef;
+/**
+ * Access CRDT internals for a TypedDoc.
+ */
+declare function loro<Shape extends DocShape>(doc: TypedDoc<Shape>): LoroTypedDocRef;
+/**
+ * Access CRDT internals for any TypedRef.
+ */
+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;
+    getDoc: () => LoroDoc;
 };
-declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
-    protected _params: TypedRefParams<Shape>;
-    protected _cachedContainer?: ShapeToContainer<Shape>;
-    constructor(_params: TypedRefParams<Shape>);
+/**
+ * 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>;
-    protected get shape(): Shape;
-    protected get placeholder(): Infer<Shape> | undefined;
-    protected get autoCommit(): boolean;
-    protected get batchedMutation(): boolean;
-    protected get doc(): LoroDoc | undefined;
     /**
-     * Commits changes if autoCommit is enabled.
-     * Call this after any mutation operation.
+     * Access the loro() namespace via the well-known symbol.
+     * This is used by the loro() function to access CRDT internals.
      */
-    protected commitIfAuto(): void;
-    protected get container(): ShapeToContainer<Shape>;
+    get [LORO_SYMBOL](): LoroRefBase;
 }
 
-declare class CounterRef extends TypedRef<CounterContainerShape> {
-    private _materialized;
-    protected get container(): LoroCounter;
-    absorbPlainValues(): void;
+/**
+ * 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;
-    /**
-     * Returns the counter value.
-     * If the counter hasn't been materialized (no operations performed),
-     * returns the placeholder value if available.
-     */
-    get value(): number;
-    valueOf(): number;
-    toJSON(): number;
-    [Symbol.toPrimitive](hint: string): number | string;
-}
-
-declare abstract class ListRefBase<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"], MutableItem = NestedShape["_mutable"]> extends TypedRef<any> {
-    private itemCache;
-    protected get container(): LoroList | LoroMovableList;
-    protected get shape(): ListContainerShape<NestedShape> | MovableListContainerShape<NestedShape>;
-    absorbPlainValues(): void;
-    protected abstract absorbValueAtIndex(index: number, value: any): void;
-    protected insertWithConversion(index: number, item: Item): void;
-    protected pushWithConversion(item: Item): void;
-    getTypedRefParams(index: number, shape: ContainerShape): TypedRefParams<ContainerShape>;
-    protected getPredicateItem(index: number): Item;
-    protected getMutableItem(index: number): any;
-    find(predicate: (item: Item, index: number) => boolean): MutableItem | undefined;
-    findIndex(predicate: (item: Item, index: number) => boolean): number;
-    map<ReturnType>(callback: (item: Item, index: number) => ReturnType): ReturnType[];
-    filter(predicate: (item: Item, index: number) => boolean): MutableItem[];
-    forEach(callback: (item: Item, index: number) => void): void;
-    some(predicate: (item: Item, index: number) => boolean): boolean;
-    every(predicate: (item: Item, index: number) => boolean): boolean;
-    slice(start?: number, end?: number): MutableItem[];
-    insert(index: number, item: Item): void;
-    delete(index: number, len: number): void;
-    push(item: Item): void;
-    pushContainer(container: Container): Container;
-    insertContainer(index: number, container: Container): Container;
-    get(index: number): MutableItem | undefined;
-    toArray(): Item[];
-    toJSON(): Item[];
-    [Symbol.iterator](): IterableIterator<MutableItem>;
-    get length(): number;
-    private updateCacheForDelete;
-    private updateCacheForInsert;
-}
-
-declare class ListRef<NestedShape extends ContainerOrValueShape> extends ListRefBase<NestedShape> {
-    [index: number]: InferMutableType<NestedShape> | undefined;
-    protected get container(): LoroList;
-    protected absorbValueAtIndex(index: number, value: any): void;
-}
-
-declare class MovableListRef<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"]> extends ListRefBase<NestedShape> {
-    [index: number]: InferMutableType<NestedShape> | undefined;
-    protected get container(): LoroMovableList;
-    protected absorbValueAtIndex(index: number, value: any): void;
-    move(from: number, to: number): void;
-    set(index: number, item: Exclude<Item, Container>): void;
-}
-
-declare class RecordRef<NestedShape extends ContainerOrValueShape> extends TypedRef<any> {
-    [key: string]: InferMutableType<NestedShape> | undefined | any;
-    private refCache;
-    protected get shape(): RecordContainerShape<NestedShape>;
-    protected get container(): LoroMap;
+    /** Get the current counter value */
+    getValue(): number;
+    /** No plain values in counter */
     absorbPlainValues(): void;
-    getTypedRefParams<S extends ContainerShape>(key: string, shape: S): TypedRefParams<ContainerShape>;
-    /**
-     * 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.
-     */
-    getRef(key: string): any;
-    /**
-     * 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.
-     */
-    getOrCreateRef(key: string): any;
-    get(key: string): InferMutableType<NestedShape> | undefined;
-    set(key: string, value: any): void;
-    setContainer<C extends Container>(key: string, container: C): C;
-    delete(key: string): void;
-    has(key: string): boolean;
-    keys(): string[];
-    values(): any[];
-    get size(): number;
-    toJSON(): Record<string, Infer<NestedShape>>;
+    /** Create the loro namespace for counter */
+    protected createLoroNamespace(): LoroCounterRef;
 }
 
 /**
- * Typed ref for struct containers (objects with fixed keys).
- * Uses LoroMap as the underlying container.
+ * Counter typed ref - thin facade that delegates to CounterRefInternals.
  */
-declare class StructRef<NestedShapes extends Record<string, ContainerOrValueShape>> extends TypedRef<any> {
-    private propertyCache;
-    constructor(params: TypedRefParams<StructContainerShape<NestedShapes>>);
-    protected get shape(): StructContainerShape<NestedShapes>;
-    protected get container(): LoroMap;
-    absorbPlainValues(): void;
-    getTypedRefParams<S extends ContainerShape>(key: string, shape: S): TypedRefParams<ContainerShape>;
-    getOrCreateRef<Shape extends ContainerShape | ValueShape>(key: string, shape: Shape): any;
-    private createLazyProperties;
-    toJSON(): Infer<StructContainerShape<NestedShapes>>;
-    get(key: string): any;
-    set(key: string, value: Value): void;
-    setContainer<C extends Container>(key: string, container: C): C;
-    delete(key: string): void;
-    has(key: string): boolean;
-    keys(): string[];
-    values(): any[];
-    get size(): number;
-}
-
-declare class TextRef extends TypedRef<TextContainerShape> {
-    private _materialized;
-    protected get container(): LoroText;
-    absorbPlainValues(): void;
-    insert(index: number, content: string): void;
-    delete(index: number, len: number): void;
-    /**
-     * Returns the text content.
-     * If the text hasn't been materialized (no operations performed),
-     * returns the placeholder value if available.
-     */
-    toString(): string;
-    valueOf(): string;
-    toJSON(): string;
-    [Symbol.toPrimitive](_hint: string): string;
-    update(text: string): void;
-    mark(range: {
-        start: number;
-        end: number;
-    }, key: string, value: any): void;
-    unmark(range: {
-        start: number;
-        end: number;
-    }, key: string): void;
-    toDelta(): any[];
-    applyDelta(delta: any[]): void;
-    get length(): number;
+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 & {
@@ -286,14 +1016,43 @@ type TreeNodeJSON<DataShape extends StructContainerShape> = {
     data: DataShape["_plain"];
     children: TreeNodeJSON<DataShape>[];
 };
+/**
+ * Interface describing the TreeRef API for use in shape definitions.
+ * This avoids circular type references that would occur with the TreeRef class.
+ * @internal
+ */
+interface TreeRefInterface<DataShape extends StructContainerShape> {
+    /** Get or create a node ref for a LoroTreeNode */
+    getOrCreateNodeRef(node: unknown): TreeNodeRef<DataShape>;
+    /** Get a node by its ID */
+    getNodeByID(id: TreeID): TreeNodeRef<DataShape> | undefined;
+    /** Delete a node from the tree */
+    delete(target: TreeID | TreeNodeRef<DataShape>): void;
+    /** Serialize the tree to a nested JSON structure */
+    toJSON(): TreeNodeJSON<DataShape>[];
+    /** Create a new root node with optional initial data */
+    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>[];
+    /** Check if a node with the given ID exists in the tree */
+    has(id: TreeID): boolean;
+    /** Enable fractional index generation for ordering */
+    enableFractionalIndex(jitter?: number): void;
+    /** Get a flat array representation of all nodes */
+    toArray(): Array<{
+        id: TreeID;
+        parent: TreeID | null;
+        index: number;
+        fractionalIndex: string;
+        data: DataShape["_plain"];
+    }>;
+}
 /**
  * Container shape for tree (forest) structures.
  * Each node in the tree has typed metadata stored in a LoroMap.
  *
- * Note: The Mutable type (second generic parameter) is `any` here to avoid
- * circular dependency with TreeRef. The actual type is resolved at runtime
- * and through the InferMutableType helper.
- *
  * @example
  * ```typescript
  * const StateNodeDataShape = Shape.struct({
@@ -306,7 +1065,7 @@ type TreeNodeJSON<DataShape extends StructContainerShape> = {
  * })
  * ```
  */
-interface TreeContainerShape<DataShape extends StructContainerShape = StructContainerShape> extends Shape<TreeNodeJSON<DataShape>[], any, never[]> {
+interface TreeContainerShape<DataShape extends StructContainerShape = StructContainerShape> extends Shape<TreeNodeJSON<DataShape>[], TreeRefInterface<DataShape>, never[]> {
     readonly _type: "tree";
     /**
      * The shape of each node's data (metadata).
@@ -528,7 +1287,7 @@ declare const Shape: {
      *   states: Shape.tree(StateNodeDataShape),
      * })
      *
-     * doc.$.change(draft => {
+     * doc.change(draft => {
      *   const root = draft.states.createNode({ name: "idle", facts: {} })
      *   const child = root.createNode({ name: "running", facts: {} })
      *   child.data.name = "active"
@@ -634,180 +1393,6 @@ declare function derivePlaceholder<T extends DocShape>(schema: T): InferPlacehol
  */
 declare function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown;
 
-/** biome-ignore-all lint/suspicious/noExplicitAny: JSON Patch values can be any type */
-
-type JsonPatchAddOperation = {
-    op: "add";
-    path: string | (string | number)[];
-    value: any;
-};
-type JsonPatchRemoveOperation = {
-    op: "remove";
-    path: string | (string | number)[];
-};
-type JsonPatchReplaceOperation = {
-    op: "replace";
-    path: string | (string | number)[];
-    value: any;
-};
-type JsonPatchMoveOperation = {
-    op: "move";
-    path: string | (string | number)[];
-    from: string | (string | number)[];
-};
-type JsonPatchCopyOperation = {
-    op: "copy";
-    path: string | (string | number)[];
-    from: string | (string | number)[];
-};
-type JsonPatchTestOperation = {
-    op: "test";
-    path: string | (string | number)[];
-    value: any;
-};
-type JsonPatchOperation = JsonPatchAddOperation | JsonPatchRemoveOperation | JsonPatchReplaceOperation | JsonPatchMoveOperation | JsonPatchCopyOperation | JsonPatchTestOperation;
-type JsonPatch = JsonPatchOperation[];
-
-/** biome-ignore-all lint/suspicious/noExplicitAny: fix later */
-
-/**
- * Meta-operations namespace for TypedDoc.
- * Access via doc.$ to perform batch operations, serialization, etc.
- */
-declare class TypedDocMeta<Shape extends DocShape> {
-    private internal;
-    constructor(internal: TypedDocInternal<Shape>);
-    /**
-     * 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: (draft: Mutable<Shape>) => void): TypedDoc<Shape>;
-    /**
-     * Returns the full plain JavaScript object representation of the document.
-     * This is an expensive O(N) operation that serializes the entire document.
-     */
-    toJSON(): Infer<Shape>;
-    /**
-     * 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: JsonPatch, pathPrefix?: (string | number)[]): TypedDoc<Shape>;
-    /**
-     * Access the underlying LoroDoc for advanced operations.
-     */
-    get loroDoc(): LoroDoc;
-    /**
-     * Access the document schema shape.
-     */
-    get docShape(): Shape;
-    /**
-     * Get raw CRDT value without placeholder overlay.
-     */
-    get rawValue(): any;
-}
-/**
- * Internal TypedDoc implementation (not directly exposed to users).
- * Users interact with the proxied version that provides direct schema access.
- */
-declare class TypedDocInternal<Shape extends DocShape> {
-    private shape;
-    private placeholder;
-    private doc;
-    private _valueRef;
-    proxy: TypedDoc<Shape> | null;
-    constructor(shape: Shape, doc?: LoroDoc);
-    get value(): Mutable<Shape>;
-    toJSON(): Infer<Shape>;
-    change(fn: (draft: Mutable<Shape>) => void): void;
-    applyPatch(patch: JsonPatch, pathPrefix?: (string | number)[]): void;
-    get loroDoc(): LoroDoc;
-    get docShape(): Shape;
-    get rawValue(): any;
-}
-/**
- * The proxied TypedDoc type that provides direct schema access.
- * Schema properties are accessed directly on the doc object.
- * Meta-operations are available via the $ namespace.
- *
- * @example
- * ```typescript
- * const doc = createTypedDoc(schema);
- *
- * // Direct schema access
- * doc.count.increment(5);
- * doc.title.insert(0, "Hello");
- *
- * // Serialize to JSON (works on doc and all refs)
- * const snapshot = doc.toJSON();
- * const users = doc.users.toJSON();
- *
- * // Meta-operations via $ (escape hatch)
- * doc.$.change(draft => { ... });
- * doc.$.loroDoc;
- * ```
- */
-type TypedDoc<Shape extends DocShape> = Mutable<Shape> & {
-    /**
-     * Meta-operations namespace.
-     * Use for change(), loroDoc, etc.
-     */
-    $: TypedDocMeta<Shape>;
-    /**
-     * Returns the full plain JavaScript object representation of the document.
-     * This is an O(N) operation that serializes the entire document.
-     *
-     * @example
-     * ```typescript
-     * const snapshot = doc.toJSON();
-     * console.log(snapshot.count); // number
-     * ```
-     */
-    toJSON(): Infer<Shape>;
-};
-/**
- * Creates a new TypedDoc with the given schema.
- * Returns a proxied document where schema properties are accessed directly.
- *
- * @param shape - The document schema (with optional .placeholder() values)
- * @param existingDoc - Optional existing LoroDoc to wrap
- * @returns A proxied TypedDoc with direct schema access and $ namespace
- *
- * @example
- * ```typescript
- * const schema = Shape.doc({
- *   title: Shape.text(),
- *   count: Shape.counter(),
- * });
- *
- * const doc = createTypedDoc(schema);
- *
- * // Direct mutations (auto-commit)
- * doc.count.increment(5);
- * doc.title.insert(0, "Hello");
- *
- * // Batched mutations are committed together via `change`
- * doc.$.change(draft => {
- *   draft.count.increment(10);
- *   draft.title.update("World");
- * });
- *
- * // Get plain JSON
- * const snapshot = doc.toJSON();
- * ```
- */
-declare function createTypedDoc<Shape extends DocShape>(shape: Shape, existingDoc?: LoroDoc): TypedDoc<Shape>;
-
 /**
  * The primary method of mutating typed documents.
  * Batches multiple mutations into a single transaction.
@@ -840,20 +1425,62 @@ declare function createTypedDoc<Shape extends DocShape>(shape: Shape, existingDo
 declare function change<Shape extends DocShape>(doc: TypedDoc<Shape>, fn: (draft: Mutable<Shape>) => void): TypedDoc<Shape>;
 /**
  * Access the underlying LoroDoc for advanced operations.
+ * Works on both TypedDoc and any typed ref (TextRef, CounterRef, ListRef, etc.).
  *
- * @param doc - The TypedDoc to unwrap
- * @returns The underlying LoroDoc instance
+ * @param docOrRef - The TypedDoc or typed ref to unwrap
+ * @returns The underlying LoroDoc instance (or undefined for refs created outside a doc context)
  *
  * @example
  * ```typescript
  * import { getLoroDoc } from "@loro-extended/change"
  *
+ * // From TypedDoc
  * const loroDoc = getLoroDoc(doc)
  * const version = loroDoc.version()
  * loroDoc.subscribe(() => console.log("changed"))
+ *
+ * // From any ref (TextRef, CounterRef, ListRef, etc.)
+ * const titleRef = doc.title
+ * const loroDoc = getLoroDoc(titleRef)
+ * loroDoc?.subscribe(() => console.log("changed"))
  * ```
  */
 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;
+/**
+ * Access the underlying Loro container from a typed ref.
+ * Returns the correctly-typed container based on the ref type.
+ *
+ * @param ref - The typed ref to unwrap
+ * @returns The underlying Loro container (LoroText, LoroCounter, LoroList, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { getLoroContainer } from "@loro-extended/change"
+ *
+ * const titleRef = doc.title
+ * const loroText = getLoroContainer(titleRef)  // LoroText
+ *
+ * const countRef = doc.count
+ * const loroCounter = getLoroContainer(countRef)  // LoroCounter
+ *
+ * const itemsRef = doc.items
+ * const loroList = getLoroContainer(itemsRef)  // LoroList
+ *
+ * // Subscribe to container-level changes
+ * loroText.subscribe((event) => console.log("Text changed:", event))
+ * ```
+ */
+declare function getLoroContainer(ref: TypedRef<TextContainerShape>): LoroText;
+declare function getLoroContainer(ref: TypedRef<CounterContainerShape>): LoroCounter;
+declare function getLoroContainer(ref: TypedRef<ListContainerShape>): LoroList;
+declare function getLoroContainer(ref: TypedRef<MovableListContainerShape>): LoroMovableList;
+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<Shape extends ContainerShape>(ref: TypedRef<Shape>): ShapeToContainer<Shape>;
 
 /**
  * Overlays CRDT state with placeholder defaults
@@ -996,4 +1623,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, type DiscriminatedUnionValueShape, type DocShape, type Infer, type InferMutableType, type InferPlaceholderType, type InferRaw, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type Mutable, type ObjectValueShape, type PathBuilder, type PathNode, type PathSegment, type PathSelector, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StructContainerShape, type StructValueShape, type TextContainerShape, type TreeContainerShape, type TypedDoc, type UnionValueShape, type ValueShape, type WithNullable, type WithPlaceholder, change, compileToJsonPath, createPathBuilder, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, evaluatePath, evaluatePathOnValue, getLoroDoc, hasWildcard, mergeValue, overlayPlaceholder, validatePlaceholder };
+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 };