@loro-extended/change 0.7.0 → 0.8.1

package/dist/index.js

@@ -1,4 +1,446 @@
-// src/change.ts
+// src/derive-placeholder.ts
+function derivePlaceholder(schema) {
+  const result = {};
+  for (const [key, shape] of Object.entries(schema.shapes)) {
+    result[key] = deriveShapePlaceholder(shape);
+  }
+  return result;
+}
+function deriveShapePlaceholder(shape) {
+  switch (shape._type) {
+    // Leaf containers - use _placeholder directly
+    case "text":
+      return shape._placeholder;
+    case "counter":
+      return shape._placeholder;
+    // Dynamic containers - always empty (no per-entry merging)
+    case "list":
+    case "movableList":
+    case "tree":
+      return [];
+    case "record":
+      return {};
+    // Structured container - recurse into nested shapes
+    case "map": {
+      const result = {};
+      for (const [key, nestedShape] of Object.entries(shape.shapes)) {
+        result[key] = deriveShapePlaceholder(nestedShape);
+      }
+      return result;
+    }
+    case "value":
+      return deriveValueShapePlaceholder(shape);
+    default:
+      return void 0;
+  }
+}
+function deriveValueShapePlaceholder(shape) {
+  switch (shape.valueType) {
+    // Leaf values - use _placeholder directly
+    case "string":
+      return shape._placeholder;
+    case "number":
+      return shape._placeholder;
+    case "boolean":
+      return shape._placeholder;
+    case "null":
+      return null;
+    case "undefined":
+      return void 0;
+    case "uint8array":
+      return shape._placeholder;
+    // Structured value - recurse into nested shapes (like map)
+    case "object": {
+      const result = {};
+      for (const [key, nestedShape] of Object.entries(shape.shape)) {
+        result[key] = deriveValueShapePlaceholder(nestedShape);
+      }
+      return result;
+    }
+    // Dynamic values - always empty
+    case "array":
+      return [];
+    case "record":
+      return {};
+    // Unions - use _placeholder if explicitly set, otherwise derive from first variant
+    case "union": {
+      const placeholder = shape._placeholder;
+      if (placeholder !== void 0) {
+        if (placeholder === null || typeof placeholder !== "object") {
+          return placeholder;
+        }
+        if (Object.keys(placeholder).length > 0) {
+          return placeholder;
+        }
+      }
+      return deriveValueShapePlaceholder(shape.shapes[0]);
+    }
+    case "discriminatedUnion": {
+      const placeholder = shape._placeholder;
+      if (placeholder !== void 0) {
+        if (placeholder === null || typeof placeholder !== "object") {
+          return placeholder;
+        }
+        if (Object.keys(placeholder).length > 0) {
+          return placeholder;
+        }
+      }
+      const firstKey = Object.keys(shape.variants)[0];
+      return deriveValueShapePlaceholder(shape.variants[firstKey]);
+    }
+    default:
+      return void 0;
+  }
+}
+
+// src/utils/type-guards.ts
+import { isContainer, isContainerId } from "loro-crdt";
+function isContainerShape(schema) {
+  return schema._type && schema._type !== "value";
+}
+function isValueShape(schema) {
+  return schema._type === "value" && [
+    "string",
+    "number",
+    "boolean",
+    "null",
+    "undefined",
+    "uint8array",
+    "object",
+    "record",
+    "array",
+    "union",
+    "discriminatedUnion"
+  ].includes(schema.valueType);
+}
+function isObjectValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Uint8Array);
+}
+
+// src/overlay.ts
+function overlayPlaceholder(shape, crdtValue, placeholderValue) {
+  if (typeof crdtValue !== "object") {
+    throw new Error("crdt object is required");
+  }
+  if (typeof placeholderValue !== "object") {
+    throw new Error("placeholder object is required");
+  }
+  const result = { ...placeholderValue };
+  for (const [key, propShape] of Object.entries(shape.shapes)) {
+    const propCrdtValue = crdtValue[key];
+    const propPlaceholderValue = placeholderValue[key];
+    result[key] = mergeValue(
+      propShape,
+      propCrdtValue,
+      propPlaceholderValue
+    );
+  }
+  return result;
+}
+function mergeValue(shape, crdtValue, placeholderValue) {
+  if (crdtValue === void 0 && placeholderValue === void 0) {
+    throw new Error("either crdt or placeholder value must be defined");
+  }
+  switch (shape._type) {
+    case "text":
+      return crdtValue ?? placeholderValue ?? "";
+    case "counter":
+      return crdtValue ?? placeholderValue ?? 0;
+    case "list":
+    case "movableList":
+      return crdtValue ?? placeholderValue ?? [];
+    case "map": {
+      if (!isObjectValue(crdtValue) && crdtValue !== void 0) {
+        throw new Error("map crdt must be object");
+      }
+      const crdtMapValue = crdtValue ?? {};
+      if (!isObjectValue(placeholderValue) && placeholderValue !== void 0) {
+        throw new Error("map placeholder must be object");
+      }
+      const placeholderMapValue = placeholderValue ?? {};
+      const result = { ...placeholderMapValue };
+      for (const [key, nestedShape] of Object.entries(shape.shapes)) {
+        const nestedCrdtValue = crdtMapValue[key];
+        const nestedPlaceholderValue = placeholderMapValue[key];
+        result[key] = mergeValue(
+          nestedShape,
+          nestedCrdtValue,
+          nestedPlaceholderValue
+        );
+      }
+      return result;
+    }
+    case "tree":
+      return crdtValue ?? placeholderValue ?? [];
+    default:
+      if (shape._type === "value" && shape.valueType === "object") {
+        const crdtObj = crdtValue ?? {};
+        const placeholderObj = placeholderValue ?? {};
+        const result = { ...placeholderObj };
+        if (typeof crdtObj !== "object" || crdtObj === null) {
+          return crdtValue ?? placeholderValue;
+        }
+        for (const [key, propShape] of Object.entries(shape.shape)) {
+          const propCrdt = crdtObj[key];
+          const propPlaceholder = placeholderObj[key];
+          result[key] = mergeValue(propShape, propCrdt, propPlaceholder);
+        }
+        return result;
+      }
+      if (shape._type === "value" && shape.valueType === "discriminatedUnion") {
+        return mergeDiscriminatedUnion(
+          shape,
+          crdtValue,
+          placeholderValue
+        );
+      }
+      return crdtValue ?? placeholderValue;
+  }
+}
+function mergeDiscriminatedUnion(shape, crdtValue, placeholderValue) {
+  const crdtObj = crdtValue ?? {};
+  const placeholderObj = placeholderValue ?? {};
+  const discriminantValue = crdtObj[shape.discriminantKey] ?? placeholderObj[shape.discriminantKey];
+  if (typeof discriminantValue !== "string") {
+    return placeholderValue;
+  }
+  const variantShape = shape.variants[discriminantValue];
+  if (!variantShape) {
+    return crdtValue ?? placeholderValue;
+  }
+  const placeholderDiscriminant = placeholderObj[shape.discriminantKey];
+  const effectivePlaceholderValue = placeholderDiscriminant === discriminantValue ? placeholderValue : void 0;
+  return mergeValue(variantShape, crdtValue, effectivePlaceholderValue);
+}
+
+// src/shape.ts
+var Shape = {
+  doc: (shape) => ({
+    _type: "doc",
+    shapes: shape,
+    _plain: {},
+    _draft: {},
+    _placeholder: {}
+  }),
+  // CRDTs are represented by Loro Containers--they converge on state using Loro's
+  // various CRDT algorithms
+  counter: () => {
+    const base = {
+      _type: "counter",
+      _plain: 0,
+      _draft: {},
+      _placeholder: 0
+    };
+    return Object.assign(base, {
+      placeholder(value) {
+        return { ...base, _placeholder: value };
+      }
+    });
+  },
+  list: (shape) => ({
+    _type: "list",
+    shape,
+    _plain: [],
+    _draft: {},
+    _placeholder: []
+  }),
+  map: (shape) => ({
+    _type: "map",
+    shapes: shape,
+    _plain: {},
+    _draft: {},
+    _placeholder: {}
+  }),
+  record: (shape) => ({
+    _type: "record",
+    shape,
+    _plain: {},
+    _draft: {},
+    _placeholder: {}
+  }),
+  movableList: (shape) => ({
+    _type: "movableList",
+    shape,
+    _plain: [],
+    _draft: {},
+    _placeholder: []
+  }),
+  text: () => {
+    const base = {
+      _type: "text",
+      _plain: "",
+      _draft: {},
+      _placeholder: ""
+    };
+    return Object.assign(base, {
+      placeholder(value) {
+        return { ...base, _placeholder: value };
+      }
+    });
+  },
+  tree: (shape) => ({
+    _type: "tree",
+    shape,
+    _plain: {},
+    _draft: {},
+    _placeholder: []
+  }),
+  // Values are represented as plain JS objects, with the limitation that they MUST be
+  // representable as a Loro "Value"--basically JSON. The behavior of a Value is basically
+  // "Last Write Wins", meaning there is no subtle convergent behavior here, just taking
+  // the most recent value based on the current available information.
+  plain: {
+    string: (...options) => {
+      const base = {
+        _type: "value",
+        valueType: "string",
+        _plain: options[0] ?? "",
+        _draft: options[0] ?? "",
+        _placeholder: options[0] ?? "",
+        options: options.length > 0 ? options : void 0
+      };
+      return Object.assign(base, {
+        placeholder(value) {
+          return { ...base, _placeholder: value };
+        }
+      });
+    },
+    number: () => {
+      const base = {
+        _type: "value",
+        valueType: "number",
+        _plain: 0,
+        _draft: 0,
+        _placeholder: 0
+      };
+      return Object.assign(base, {
+        placeholder(value) {
+          return { ...base, _placeholder: value };
+        }
+      });
+    },
+    boolean: () => {
+      const base = {
+        _type: "value",
+        valueType: "boolean",
+        _plain: false,
+        _draft: false,
+        _placeholder: false
+      };
+      return Object.assign(base, {
+        placeholder(value) {
+          return { ...base, _placeholder: value };
+        }
+      });
+    },
+    null: () => ({
+      _type: "value",
+      valueType: "null",
+      _plain: null,
+      _draft: null,
+      _placeholder: null
+    }),
+    undefined: () => ({
+      _type: "value",
+      valueType: "undefined",
+      _plain: void 0,
+      _draft: void 0,
+      _placeholder: void 0
+    }),
+    uint8Array: () => ({
+      _type: "value",
+      valueType: "uint8array",
+      _plain: new Uint8Array(),
+      _draft: new Uint8Array(),
+      _placeholder: new Uint8Array()
+    }),
+    object: (shape) => ({
+      _type: "value",
+      valueType: "object",
+      shape,
+      _plain: {},
+      _draft: {},
+      _placeholder: {}
+    }),
+    record: (shape) => ({
+      _type: "value",
+      valueType: "record",
+      shape,
+      _plain: {},
+      _draft: {},
+      _placeholder: {}
+    }),
+    array: (shape) => ({
+      _type: "value",
+      valueType: "array",
+      shape,
+      _plain: [],
+      _draft: [],
+      _placeholder: []
+    }),
+    // Special value type that helps make things like `string | null` representable
+    // TODO(duane): should this be a more general type for containers too?
+    union: (shapes) => {
+      const base = {
+        _type: "value",
+        valueType: "union",
+        shapes,
+        _plain: {},
+        _draft: {},
+        _placeholder: {}
+      };
+      return Object.assign(base, {
+        placeholder(value) {
+          return { ...base, _placeholder: value };
+        }
+      });
+    },
+    /**
+     * Creates a discriminated union shape for type-safe tagged unions.
+     *
+     * @example
+     * ```typescript
+     * const ClientPresenceShape = Shape.plain.object({
+     *   type: Shape.plain.string("client"),
+     *   name: Shape.plain.string(),
+     *   input: Shape.plain.object({ force: Shape.plain.number(), angle: Shape.plain.number() }),
+     * })
+     *
+     * const ServerPresenceShape = Shape.plain.object({
+     *   type: Shape.plain.string("server"),
+     *   cars: Shape.plain.record(Shape.plain.object({ x: Shape.plain.number(), y: Shape.plain.number() })),
+     *   tick: Shape.plain.number(),
+     * })
+     *
+     * const GamePresenceSchema = Shape.plain.discriminatedUnion("type", {
+     *   client: ClientPresenceShape,
+     *   server: ServerPresenceShape,
+     * })
+     * ```
+     *
+     * @param discriminantKey - The key used to discriminate between variants (e.g., "type")
+     * @param variants - A record mapping discriminant values to their object shapes
+     */
+    discriminatedUnion: (discriminantKey, variants) => {
+      const base = {
+        _type: "value",
+        valueType: "discriminatedUnion",
+        discriminantKey,
+        variants,
+        _plain: {},
+        _draft: {},
+        _placeholder: {}
+      };
+      return Object.assign(base, {
+        placeholder(value) {
+          return { ...base, _placeholder: value };
+        }
+      });
+    }
+  }
+};
+
+// src/typed-doc.ts
 import { LoroDoc } from "loro-crdt";
 
 // src/draft-nodes/base.ts
@@ -10,8 +452,11 @@ var DraftNode = class {
   get shape() {
     return this._params.shape;
   }
-  get emptyState() {
-    return this._params.emptyState;
+  get placeholder() {
+    return this._params.placeholder;
+  }
+  get readonly() {
+    return !!this._params.readonly;
   }
   get container() {
     if (!this._cachedContainer) {
@@ -46,32 +491,6 @@ import {
   LoroMovableList,
   LoroText
 } from "loro-crdt";
-
-// src/utils/type-guards.ts
-import { isContainer, isContainerId } from "loro-crdt";
-function isContainerShape(schema) {
-  return schema._type && schema._type !== "value";
-}
-function isValueShape(schema) {
-  return schema._type === "value" && [
-    "string",
-    "number",
-    "boolean",
-    "null",
-    "undefined",
-    "uint8array",
-    "object",
-    "record",
-    "array",
-    "union",
-    "discriminatedUnion"
-  ].includes(schema.valueType);
-}
-function isObjectValue(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Uint8Array);
-}
-
-// src/conversion.ts
 function convertTextInput(value) {
   const text = new LoroText();
   text.insert(0, value);
@@ -242,15 +661,16 @@ var ListDraftNodeBase = class extends DraftNode {
   getDraftNodeParams(index, shape) {
     return {
       shape,
-      emptyState: void 0,
-      // List items don't have empty state
+      placeholder: void 0,
+      // List items don't have placeholder
       getContainer: () => {
         const containerItem = this.container.get(index);
         if (!containerItem || !isContainer(containerItem)) {
           throw new Error(`No container found at index ${index}`);
         }
         return containerItem;
-      }
+      },
+      readonly: this.readonly
     };
   }
   // Get item for predicate functions - always returns plain Item for filtering logic
@@ -294,13 +714,24 @@ var ListDraftNodeBase = class extends DraftNode {
       } else {
         cachedItem = containerItem;
       }
-      this.itemCache.set(index, cachedItem);
+      if (!this.readonly) {
+        this.itemCache.set(index, cachedItem);
+      }
       return cachedItem;
     } else {
       cachedItem = createContainerDraftNode(
         this.getDraftNodeParams(index, this.shape.shape)
       );
       this.itemCache.set(index, cachedItem);
+      if (this.readonly) {
+        const shape = this.shape.shape;
+        if (shape._type === "counter") {
+          return cachedItem.value;
+        }
+        if (shape._type === "text") {
+          return cachedItem.toString();
+        }
+      }
       return cachedItem;
     }
   }
@@ -367,20 +798,25 @@ var ListDraftNodeBase = class extends DraftNode {
     return true;
   }
   insert(index, item) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     this.updateCacheForInsert(index);
     this.insertWithConversion(index, item);
   }
   delete(index, len) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     this.updateCacheForDelete(index, len);
     this.container.delete(index, len);
   }
   push(item) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     this.pushWithConversion(item);
   }
   pushContainer(container) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     return this.container.pushContainer(container);
   }
   insertContainer(index, container) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     return this.container.insertContainer(index, container);
   }
   get(index) {
@@ -469,12 +905,13 @@ var MapDraftNode = class extends DraftNode {
     }
   }
   getDraftNodeParams(key, shape) {
-    const emptyState = this.emptyState?.[key];
+    const placeholder = this.placeholder?.[key];
     const LoroContainer = containerConstructor[shape._type];
     return {
       shape,
-      emptyState,
-      getContainer: () => this.container.getOrCreateContainer(key, new LoroContainer())
+      placeholder,
+      getContainer: () => this.container.getOrCreateContainer(key, new LoroContainer()),
+      readonly: this.readonly
     };
   }
   getOrCreateNode(key, shape) {
@@ -482,20 +919,35 @@ var MapDraftNode = class extends DraftNode {
     if (!node) {
       if (isContainerShape(shape)) {
         node = createContainerDraftNode(this.getDraftNodeParams(key, shape));
+        this.propertyCache.set(key, node);
       } else {
         const containerValue = this.container.get(key);
         if (containerValue !== void 0) {
           node = containerValue;
         } else {
-          const emptyState = this.emptyState?.[key];
-          if (emptyState === void 0) {
-            throw new Error("empty state required");
+          const placeholder = this.placeholder?.[key];
+          if (placeholder === void 0) {
+            throw new Error("placeholder required");
           }
-          node = emptyState;
+          node = placeholder;
+        }
+        if (!this.readonly) {
+          this.propertyCache.set(key, node);
         }
       }
       if (node === void 0) throw new Error("no container made");
-      this.propertyCache.set(key, node);
+    }
+    if (this.readonly && isContainerShape(shape)) {
+      const existing = this.container.get(key);
+      if (existing === void 0) {
+        return this.placeholder?.[key];
+      }
+      if (shape._type === "counter") {
+        return node.value;
+      }
+      if (shape._type === "text") {
+        return node.toString();
+      }
     }
     return node;
   }
@@ -504,10 +956,23 @@ var MapDraftNode = class extends DraftNode {
       const shape = this.shape.shapes[key];
       Object.defineProperty(this, key, {
         get: () => this.getOrCreateNode(key, shape),
-        set: isValueShape(shape) ? (value) => {
-          this.container.set(key, value);
-          this.propertyCache.set(key, value);
-        } : void 0
+        set: (value) => {
+          if (this.readonly) throw new Error("Cannot modify readonly doc");
+          if (isValueShape(shape)) {
+            this.container.set(key, value);
+            this.propertyCache.set(key, value);
+          } else {
+            if (value && typeof value === "object") {
+              const node = this.getOrCreateNode(key, shape);
+              if (assignPlainValueToDraftNode(node, value)) {
+                return;
+              }
+            }
+            throw new Error(
+              "Cannot set container directly, modify the draft node instead"
+            );
+          }
+        }
       });
     }
   }
@@ -516,12 +981,15 @@ var MapDraftNode = class extends DraftNode {
     return this.container.get(key);
   }
   set(key, value) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     this.container.set(key, value);
   }
   setContainer(key, container) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     return this.container.setContainer(key, container);
   }
   delete(key) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     this.container.delete(key);
   }
   has(key) {
@@ -546,11 +1014,93 @@ var MovableListDraftNode = class extends ListDraftNodeBase {
   absorbValueAtIndex(index, value) {
     this.container.set(index, value);
   }
-  move(from, to) {
-    this.container.move(from, to);
+  move(from, to) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
+    this.container.move(from, to);
+  }
+  set(index, item) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
+    return this.container.set(index, item);
+  }
+};
+
+// src/draft-nodes/proxy-handlers.ts
+var recordProxyHandler = {
+  get: (target, prop) => {
+    if (typeof prop === "string" && !(prop in target)) {
+      return target.get(prop);
+    }
+    return Reflect.get(target, prop);
+  },
+  set: (target, prop, value) => {
+    if (typeof prop === "string" && !(prop in target)) {
+      target.set(prop, value);
+      return true;
+    }
+    return Reflect.set(target, prop, value);
+  },
+  deleteProperty: (target, prop) => {
+    if (typeof prop === "string" && !(prop in target)) {
+      target.delete(prop);
+      return true;
+    }
+    return Reflect.deleteProperty(target, prop);
+  },
+  ownKeys: (target) => {
+    return target.keys();
+  },
+  getOwnPropertyDescriptor: (target, prop) => {
+    if (typeof prop === "string" && target.has(prop)) {
+      return {
+        configurable: true,
+        enumerable: true,
+        value: target.get(prop)
+      };
+    }
+    return Reflect.getOwnPropertyDescriptor(target, prop);
+  }
+};
+var listProxyHandler = {
+  get: (target, prop) => {
+    if (typeof prop === "string") {
+      const index = Number(prop);
+      if (!Number.isNaN(index)) {
+        return target.get(index);
+      }
+    }
+    return Reflect.get(target, prop);
+  },
+  set: (target, prop, value) => {
+    if (typeof prop === "string") {
+      const index = Number(prop);
+      if (!Number.isNaN(index)) {
+        target.delete(index, 1);
+        target.insert(index, value);
+        return true;
+      }
+    }
+    return Reflect.set(target, prop, value);
   }
-  set(index, item) {
-    return this.container.set(index, item);
+};
+var movableListProxyHandler = {
+  get: (target, prop) => {
+    if (typeof prop === "string") {
+      const index = Number(prop);
+      if (!Number.isNaN(index)) {
+        return target.get(index);
+      }
+    }
+    return Reflect.get(target, prop);
+  },
+  set: (target, prop, value) => {
+    if (typeof prop === "string") {
+      const index = Number(prop);
+      if (!Number.isNaN(index)) {
+        target.set(index, value);
+        return true;
+      }
+    }
+    return Reflect.set(target, prop, value);
   }
 };
 
@@ -574,44 +1124,6 @@ var containerConstructor2 = {
 };
 var RecordDraftNode = class extends DraftNode {
   nodeCache = /* @__PURE__ */ new Map();
-  constructor(params) {
-    super(params);
-    return new Proxy(this, {
-      get: (target, prop) => {
-        if (typeof prop === "string" && !(prop in target)) {
-          return target.get(prop);
-        }
-        return Reflect.get(target, prop);
-      },
-      set: (target, prop, value) => {
-        if (typeof prop === "string" && !(prop in target)) {
-          target.set(prop, value);
-          return true;
-        }
-        return Reflect.set(target, prop, value);
-      },
-      deleteProperty: (target, prop) => {
-        if (typeof prop === "string" && !(prop in target)) {
-          target.delete(prop);
-          return true;
-        }
-        return Reflect.deleteProperty(target, prop);
-      },
-      ownKeys: (target) => {
-        return target.keys();
-      },
-      getOwnPropertyDescriptor: (target, prop) => {
-        if (typeof prop === "string" && target.has(prop)) {
-          return {
-            configurable: true,
-            enumerable: true,
-            value: target.get(prop)
-          };
-        }
-        return Reflect.getOwnPropertyDescriptor(target, prop);
-      }
-    });
-  }
   get shape() {
     return super.shape;
   }
@@ -628,12 +1140,13 @@ var RecordDraftNode = class extends DraftNode {
     }
   }
   getDraftNodeParams(key, shape) {
-    const emptyState = this.emptyState?.[key];
+    const placeholder = this.placeholder?.[key];
     const LoroContainer = containerConstructor2[shape._type];
     return {
       shape,
-      emptyState,
-      getContainer: () => this.container.getOrCreateContainer(key, new LoroContainer())
+      placeholder,
+      getContainer: () => this.container.getOrCreateContainer(key, new LoroContainer()),
+      readonly: this.readonly
     };
   }
   getOrCreateNode(key) {
@@ -644,21 +1157,31 @@ var RecordDraftNode = class extends DraftNode {
         node = createContainerDraftNode(
           this.getDraftNodeParams(key, shape)
         );
+        this.nodeCache.set(key, node);
       } else {
         const containerValue = this.container.get(key);
         if (containerValue !== void 0) {
           node = containerValue;
         } else {
-          const emptyState = this.emptyState?.[key];
-          if (emptyState === void 0) {
+          const placeholder = this.placeholder?.[key];
+          if (placeholder === void 0) {
             node = shape._plain;
           } else {
-            node = emptyState;
+            node = placeholder;
           }
         }
+        if (node !== void 0 && !this.readonly) {
+          this.nodeCache.set(key, node);
+        }
       }
-      if (node !== void 0) {
-        this.nodeCache.set(key, node);
+    }
+    if (this.readonly && isContainerShape(this.shape.shape)) {
+      const shape = this.shape.shape;
+      if (shape._type === "counter") {
+        return node.value;
+      }
+      if (shape._type === "text") {
+        return node.toString();
       }
     }
     return node;
@@ -667,19 +1190,28 @@ var RecordDraftNode = class extends DraftNode {
     return this.getOrCreateNode(key);
   }
   set(key, value) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     if (isValueShape(this.shape.shape)) {
       this.container.set(key, value);
       this.nodeCache.set(key, value);
     } else {
+      if (value && typeof value === "object") {
+        const node = this.getOrCreateNode(key);
+        if (assignPlainValueToDraftNode(node, value)) {
+          return;
+        }
+      }
       throw new Error(
         "Cannot set container directly, modify the draft node instead"
       );
     }
   }
   setContainer(key, container) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     return this.container.setContainer(key, container);
   }
   delete(key) {
+    if (this.readonly) throw new Error("Cannot modify readonly doc");
     this.container.delete(key);
     this.nodeCache.delete(key);
   }
@@ -760,16 +1292,23 @@ function createContainerDraftNode(params) {
         params
       );
     case "list":
-      return new ListDraftNode(params);
+      return new Proxy(
+        new ListDraftNode(params),
+        listProxyHandler
+      );
     case "map":
       return new MapDraftNode(params);
     case "movableList":
-      return new MovableListDraftNode(
-        params
+      return new Proxy(
+        new MovableListDraftNode(
+          params
+        ),
+        movableListProxyHandler
       );
     case "record":
-      return new RecordDraftNode(
-        params
+      return new Proxy(
+        new RecordDraftNode(params),
+        recordProxyHandler
       );
     case "text":
       return new TextDraftNode(params);
@@ -781,6 +1320,29 @@ function createContainerDraftNode(params) {
       );
   }
 }
+function assignPlainValueToDraftNode(node, value) {
+  const shapeType = node.shape._type;
+  if (shapeType === "map" || shapeType === "record") {
+    for (const k in value) {
+      ;
+      node[k] = value[k];
+    }
+    return true;
+  }
+  if (shapeType === "list" || shapeType === "movableList") {
+    if (Array.isArray(value)) {
+      const listNode = node;
+      if (listNode.length > 0) {
+        listNode.delete(0, listNode.length);
+      }
+      for (const item of value) {
+        listNode.push(item);
+      }
+      return true;
+    }
+  }
+  return false;
+}
 
 // src/draft-nodes/doc.ts
 var containerGetter = {
@@ -795,7 +1357,7 @@ var containerGetter = {
 var DraftDoc = class extends DraftNode {
   doc;
   propertyCache = /* @__PURE__ */ new Map();
-  requiredEmptyState;
+  requiredPlaceholder;
   constructor(_params) {
     super({
       ..._params,
@@ -803,25 +1365,40 @@ var DraftDoc = class extends DraftNode {
         throw new Error("can't get container on DraftDoc");
       }
     });
-    if (!_params.emptyState) throw new Error("emptyState required");
+    if (!_params.placeholder) throw new Error("placeholder required");
     this.doc = _params.doc;
-    this.requiredEmptyState = _params.emptyState;
+    this.requiredPlaceholder = _params.placeholder;
     this.createLazyProperties();
   }
   getDraftNodeParams(key, shape) {
     const getter = this.doc[containerGetter[shape._type]].bind(this.doc);
     return {
       shape,
-      emptyState: this.requiredEmptyState[key],
-      getContainer: () => getter(key)
+      placeholder: this.requiredPlaceholder[key],
+      getContainer: () => getter(key),
+      readonly: this.readonly
     };
   }
   getOrCreateDraftNode(key, shape) {
+    if (this.readonly && (shape._type === "counter" || shape._type === "text")) {
+      const shallow = this.doc.getShallowValue();
+      if (!shallow[key]) {
+        return this.requiredPlaceholder[key];
+      }
+    }
     let node = this.propertyCache.get(key);
     if (!node) {
       node = createContainerDraftNode(this.getDraftNodeParams(key, shape));
       this.propertyCache.set(key, node);
     }
+    if (this.readonly) {
+      if (shape._type === "counter") {
+        return node.value;
+      }
+      if (shape._type === "text") {
+        return node.toString();
+      }
+    }
     return node;
   }
   createLazyProperties() {
@@ -1037,102 +1614,6 @@ var JsonPatchApplicator = class {
   }
 };
 
-// src/overlay.ts
-function overlayEmptyState(shape, crdtValue, emptyValue) {
-  if (typeof crdtValue !== "object") {
-    throw new Error("crdt object is required");
-  }
-  if (typeof emptyValue !== "object") {
-    throw new Error("empty object is required");
-  }
-  const result = { ...emptyValue };
-  for (const [key, propShape] of Object.entries(shape.shapes)) {
-    const propCrdtValue = crdtValue[key];
-    const propEmptyValue = emptyValue[key];
-    result[key] = mergeValue(
-      propShape,
-      propCrdtValue,
-      propEmptyValue
-    );
-  }
-  return result;
-}
-function mergeValue(shape, crdtValue, emptyValue) {
-  if (crdtValue === void 0 && emptyValue === void 0) {
-    throw new Error("either crdt or empty value must be defined");
-  }
-  switch (shape._type) {
-    case "text":
-      return crdtValue ?? emptyValue ?? "";
-    case "counter":
-      return crdtValue ?? emptyValue ?? 0;
-    case "list":
-    case "movableList":
-      return crdtValue ?? emptyValue ?? [];
-    case "map": {
-      if (!isObjectValue(crdtValue) && crdtValue !== void 0) {
-        throw new Error("map crdt must be object");
-      }
-      const crdtMapValue = crdtValue ?? {};
-      if (!isObjectValue(emptyValue) && emptyValue !== void 0) {
-        throw new Error("map empty state must be object");
-      }
-      const emptyMapValue = emptyValue ?? {};
-      const result = { ...emptyMapValue };
-      for (const [key, nestedShape] of Object.entries(shape.shapes)) {
-        const nestedCrdtValue = crdtMapValue[key];
-        const nestedEmptyValue = emptyMapValue[key];
-        result[key] = mergeValue(
-          nestedShape,
-          nestedCrdtValue,
-          nestedEmptyValue
-        );
-      }
-      return result;
-    }
-    case "tree":
-      return crdtValue ?? emptyValue ?? [];
-    default:
-      if (shape._type === "value" && shape.valueType === "object") {
-        const crdtObj = crdtValue ?? {};
-        const emptyObj = emptyValue ?? {};
-        const result = { ...emptyObj };
-        if (typeof crdtObj !== "object" || crdtObj === null) {
-          return crdtValue ?? emptyValue;
-        }
-        for (const [key, propShape] of Object.entries(shape.shape)) {
-          const propCrdt = crdtObj[key];
-          const propEmpty = emptyObj[key];
-          result[key] = mergeValue(propShape, propCrdt, propEmpty);
-        }
-        return result;
-      }
-      if (shape._type === "value" && shape.valueType === "discriminatedUnion") {
-        return mergeDiscriminatedUnion(
-          shape,
-          crdtValue,
-          emptyValue
-        );
-      }
-      return crdtValue ?? emptyValue;
-  }
-}
-function mergeDiscriminatedUnion(shape, crdtValue, emptyValue) {
-  const crdtObj = crdtValue ?? {};
-  const emptyObj = emptyValue ?? {};
-  const discriminantValue = crdtObj[shape.discriminantKey] ?? emptyObj[shape.discriminantKey];
-  if (typeof discriminantValue !== "string") {
-    return emptyValue;
-  }
-  const variantShape = shape.variants[discriminantValue];
-  if (!variantShape) {
-    return crdtValue ?? emptyValue;
-  }
-  const emptyDiscriminant = emptyObj[shape.discriminantKey];
-  const effectiveEmptyValue = emptyDiscriminant === discriminantValue ? emptyValue : void 0;
-  return mergeValue(variantShape, crdtValue, effectiveEmptyValue);
-}
-
 // src/validation.ts
 function validateValue(value, schema, path = "") {
   if (!schema || typeof schema !== "object" || !("_type" in schema)) {
@@ -1343,53 +1824,71 @@ function validateValue(value, schema, path = "") {
   }
   throw new Error(`Unknown schema type: ${schema._type}`);
 }
-function validateEmptyState(emptyState, schema) {
-  if (!emptyState || typeof emptyState !== "object" || Array.isArray(emptyState)) {
-    throw new Error("Empty state must be an object");
+function validatePlaceholder(placeholder, schema) {
+  if (!placeholder || typeof placeholder !== "object" || Array.isArray(placeholder)) {
+    throw new Error("Placeholder must be an object");
   }
   const result = {};
   for (const [key, schemaValue] of Object.entries(schema.shapes)) {
-    const value = emptyState[key];
+    const value = placeholder[key];
     result[key] = validateValue(value, schemaValue, key);
   }
   return result;
 }
 
-// src/change.ts
+// src/typed-doc.ts
 var TypedDoc = class {
+  shape;
+  placeholder;
+  doc;
   /**
-   * Creates a new TypedDoc with the given schema and empty state.
+   * Creates a new TypedDoc with the given schema.
+   * Placeholder state is automatically derived from the schema's placeholder values.
    *
-   * @param shape - The document schema
-   * @param emptyState - Default values for the document. For dynamic containers
-   *   (list, record, etc.), only empty values ([] or {}) are allowed. Use
-   *   `.change()` to add initial data after construction.
+   * @param shape - The document schema (with optional .placeholder() values)
    * @param doc - Optional existing LoroDoc to wrap
    */
-  constructor(shape, emptyState, doc = new LoroDoc()) {
+  constructor(shape, doc = new LoroDoc()) {
     this.shape = shape;
-    this.emptyState = emptyState;
+    this.placeholder = derivePlaceholder(shape);
     this.doc = doc;
-    validateEmptyState(emptyState, shape);
+    validatePlaceholder(this.placeholder, this.shape);
   }
+  /**
+   * Returns a read-only, live view of the document.
+   * Accessing properties on this object will read directly from the underlying CRDT.
+   * This is efficient (O(1) per access) and always up-to-date.
+   */
   get value() {
+    return new DraftDoc({
+      shape: this.shape,
+      placeholder: this.placeholder,
+      doc: this.doc,
+      readonly: true
+    });
+  }
+  /**
+   * Returns the full plain JavaScript object representation of the document.
+   * This is an expensive O(N) operation that serializes the entire document.
+   */
+  toJSON() {
     const crdtValue = this.doc.toJSON();
-    return overlayEmptyState(
+    return overlayPlaceholder(
       this.shape,
       crdtValue,
-      this.emptyState
+      this.placeholder
     );
   }
   change(fn) {
     const draft = new DraftDoc({
       shape: this.shape,
-      emptyState: this.emptyState,
+      placeholder: this.placeholder,
       doc: this.doc
     });
     fn(draft);
     draft.absorbPlainValues();
     this.doc.commit();
-    return this.value;
+    return this.toJSON();
   }
   /**
    * Apply JSON Patch operations to the document
@@ -1429,193 +1928,17 @@ var TypedDoc = class {
     return this.doc.toJSON();
   }
 };
-function createTypedDoc(shape, emptyState, existingDoc) {
-  return new TypedDoc(shape, emptyState, existingDoc || new LoroDoc());
+function createTypedDoc(shape, existingDoc) {
+  return new TypedDoc(shape, existingDoc || new LoroDoc());
 }
-
-// src/shape.ts
-var Shape = {
-  doc: (shape) => ({
-    _type: "doc",
-    shapes: shape,
-    _plain: {},
-    _draft: {},
-    _emptyState: {}
-  }),
-  // CRDTs are represented by Loro Containers--they converge on state using Loro's
-  // various CRDT algorithms
-  counter: () => ({
-    _type: "counter",
-    _plain: 0,
-    _draft: {},
-    _emptyState: 0
-  }),
-  list: (shape) => ({
-    _type: "list",
-    shape,
-    _plain: [],
-    _draft: {},
-    _emptyState: []
-  }),
-  map: (shape) => ({
-    _type: "map",
-    shapes: shape,
-    _plain: {},
-    _draft: {},
-    _emptyState: {}
-  }),
-  record: (shape) => ({
-    _type: "record",
-    shape,
-    _plain: {},
-    _draft: {},
-    _emptyState: {}
-  }),
-  movableList: (shape) => ({
-    _type: "movableList",
-    shape,
-    _plain: [],
-    _draft: {},
-    _emptyState: []
-  }),
-  text: () => ({
-    _type: "text",
-    _plain: "",
-    _draft: {},
-    _emptyState: ""
-  }),
-  tree: (shape) => ({
-    _type: "tree",
-    shape,
-    _plain: {},
-    _draft: {},
-    _emptyState: []
-  }),
-  // Values are represented as plain JS objects, with the limitation that they MUST be
-  // representable as a Loro "Value"--basically JSON. The behavior of a Value is basically
-  // "Last Write Wins", meaning there is no subtle convergent behavior here, just taking
-  // the most recent value based on the current available information.
-  plain: {
-    string: (...options) => ({
-      _type: "value",
-      valueType: "string",
-      _plain: options[0] ?? "",
-      _draft: options[0] ?? "",
-      _emptyState: options[0] ?? "",
-      options: options.length > 0 ? options : void 0
-    }),
-    number: () => ({
-      _type: "value",
-      valueType: "number",
-      _plain: 0,
-      _draft: 0,
-      _emptyState: 0
-    }),
-    boolean: () => ({
-      _type: "value",
-      valueType: "boolean",
-      _plain: false,
-      _draft: false,
-      _emptyState: false
-    }),
-    null: () => ({
-      _type: "value",
-      valueType: "null",
-      _plain: null,
-      _draft: null,
-      _emptyState: null
-    }),
-    undefined: () => ({
-      _type: "value",
-      valueType: "undefined",
-      _plain: void 0,
-      _draft: void 0,
-      _emptyState: void 0
-    }),
-    uint8Array: () => ({
-      _type: "value",
-      valueType: "uint8array",
-      _plain: new Uint8Array(),
-      _draft: new Uint8Array(),
-      _emptyState: new Uint8Array()
-    }),
-    object: (shape) => ({
-      _type: "value",
-      valueType: "object",
-      shape,
-      _plain: {},
-      _draft: {},
-      _emptyState: {}
-    }),
-    record: (shape) => ({
-      _type: "value",
-      valueType: "record",
-      shape,
-      _plain: {},
-      _draft: {},
-      _emptyState: {}
-    }),
-    array: (shape) => ({
-      _type: "value",
-      valueType: "array",
-      shape,
-      _plain: [],
-      _draft: [],
-      _emptyState: []
-    }),
-    // Special value type that helps make things like `string | null` representable
-    // TODO(duane): should this be a more general type for containers too?
-    union: (shapes) => ({
-      _type: "value",
-      valueType: "union",
-      shapes,
-      _plain: {},
-      _draft: {},
-      _emptyState: {}
-    }),
-    /**
-     * Creates a discriminated union shape for type-safe tagged unions.
-     *
-     * @example
-     * ```typescript
-     * const ClientPresenceShape = Shape.plain.object({
-     *   type: Shape.plain.string("client"),
-     *   name: Shape.plain.string(),
-     *   input: Shape.plain.object({ force: Shape.plain.number(), angle: Shape.plain.number() }),
-     * })
-     *
-     * const ServerPresenceShape = Shape.plain.object({
-     *   type: Shape.plain.string("server"),
-     *   cars: Shape.plain.record(Shape.plain.object({ x: Shape.plain.number(), y: Shape.plain.number() })),
-     *   tick: Shape.plain.number(),
-     * })
-     *
-     * const GamePresenceSchema = Shape.plain.discriminatedUnion("type", {
-     *   client: ClientPresenceShape,
-     *   server: ServerPresenceShape,
-     * })
-     * ```
-     *
-     * @param discriminantKey - The key used to discriminate between variants (e.g., "type")
-     * @param variants - A record mapping discriminant values to their object shapes
-     */
-    discriminatedUnion: (discriminantKey, variants) => ({
-      _type: "value",
-      valueType: "discriminatedUnion",
-      discriminantKey,
-      variants,
-      _plain: {},
-      _draft: {},
-      _emptyState: {}
-    })
-  }
-};
 export {
   Shape,
   TypedDoc,
   createTypedDoc,
+  derivePlaceholder,
+  deriveShapePlaceholder,
   mergeValue,
-  overlayEmptyState,
-  validateEmptyState
+  overlayPlaceholder,
+  validatePlaceholder
 };
 //# sourceMappingURL=index.js.map