fix(core): reject root-level primitives in initialState (#83)

* fix(core): reject root-level primitives in initialState

LoroDoc only stores container types (Map/List/MovableList/Text/Tree)
at the document root, but Mirror previously accepted root-level
primitives (e.g. `{ version: 0 }`) in initialState and silently kept
them in memory while never writing them to the doc. This caused
`mirror.getState()` to drift from `doc.toJSON()`.

Now reject primitives both at compile time (via a `RootInitialValue`
constraint on `initialState`) and at runtime (clear error pointing
users to wrap the value in a root LoroMap). `null`/`undefined` are
still accepted as "absent".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(jotai,react): apply root primitive constraint to wrapper configs

The jotai LoroMirrorAtomConfig and react UseLoroStoreOptions
redeclare initialState with a looser type than MirrorOptions, which
broke the build after the core constraint was tightened. Mirror the
RootInitialValue intersection in both wrappers and re-export the
type from loro-mirror so consumers can reuse it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: ignore .claude/ local agent state

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Zixuan Chen <me@zxch3n.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.gitignore

@@ -3,3 +3,4 @@ dist
 # Ignore TS incremental build info everywhere in the repo
 *.tsbuildinfo
 .DS_Store
+.claude/

packages/core/src/core/index.ts

@@ -8,5 +8,6 @@ export type {
     SetStateOptions,
     SubscriberCallback,
     UpdateMetadata,
-    InferContainerOptions
+    InferContainerOptions,
+    RootInitialValue
 } from "./mirror.js";

packages/core/src/core/mirror.ts

@@ -78,6 +78,19 @@ interface MirrorStateObject {
     [k: string]: MirrorState;
 }
 
+/**
+ * Values allowed for root-level keys of `initialState`. LoroDoc only stores
+ * container types at the root, so primitives (bare `number`/`boolean`) are
+ * disallowed. A root-level `string` is permitted because it maps to a root
+ * `LoroText` container.
+ */
+export type RootInitialValue =
+    | string
+    | ReadonlyArray<unknown>
+    | { readonly [key: string]: unknown }
+    | null
+    | undefined;
+
 function hasKeyProp(c: Change): c is Extract<Change, { key: string | number }> {
     return (c as { key?: unknown }).key !== undefined;
 }
@@ -117,9 +130,16 @@ export interface MirrorOptions<S extends SchemaType> {
     schema?: S;
 
     /**
-     * Initial state (optional)
+     * Initial state (optional).
+     *
+     * LoroDoc can only hold container values at the root (Map, List,
+     * MovableList, Text, Tree), so root entries must be container-shaped:
+     * objects, arrays, strings, or `null`/`undefined`. Bare numbers and
+     * booleans are rejected at the type level (and at runtime).
      */
-    initialState?: Partial<import("../schema/index.js").InferInputType<S>>;
+    initialState?: Partial<import("../schema/index.js").InferInputType<S>> & {
+        [key: string]: RootInitialValue;
+    };
 
     /**
      * Whether to validate state updates against the schema
@@ -473,7 +493,22 @@ export class Mirror<S extends SchemaType> {
                     ? schemaToContainerType(fieldSchema)
                     : undefined) ??
                 this.inferRootContainerTypeFromInitialValue(value);
-            if (!containerType) continue;
+            if (!containerType) {
+                // null/undefined are treated as "absent" and silently skipped.
+                if (value == null) continue;
+                // LoroDoc cannot store primitives at the document root — only
+                // containers (Map, List, MovableList, Text, Tree). Silently
+                // dropping the value would cause Mirror state to drift from
+                // doc state on the next sync, so fail loudly instead.
+                const fieldType = fieldSchema?.type;
+                const observed = Array.isArray(value) ? "array" : typeof value;
+                const detail = fieldType
+                    ? `schema type "${fieldType}"`
+                    : `value of type "${observed}"`;
+                throw new Error(
+                    `initialState["${key}"] is a primitive (${detail}), but LoroDoc only supports container types (Map, List, MovableList, Text, Tree) at the root. Wrap it under a root LoroMap (e.g. a "meta" map).`,
+                );
+            }
 
             const container = getRootContainerByType(
                 this.doc,

packages/core/src/index.ts

@@ -13,6 +13,7 @@ export {
     type UpdateMetadata,
     type SubscriberCallback,
     type InferContainerOptions,
+    type RootInitialValue,
     UpdateSource,
 } from "./core/index.js";
 

packages/core/tests/mirror.test.ts

@@ -1027,6 +1027,83 @@ describe("Mirror - State Consistency", () => {
         expect(doc.toJSON()).toStrictEqual(mirror.getState());
     });
 
+    it("throws when initialState contains a primitive at the root (no schema)", () => {
+        const doc = new LoroDoc();
+        expect(
+            () =>
+                new Mirror({
+                    doc,
+                    initialState: { version: 0, notes: [] } as any,
+                }),
+        ).toThrow(/initialState\["version"\].*root/i);
+    });
+
+    it("rejects root-level primitives at the type level", () => {
+        // Type-only assertions; the function body is never executed.
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const _typeChecks = () => {
+            const doc = new LoroDoc();
+            // @ts-expect-error - bare number at root must be a TS error
+            new Mirror({ doc, initialState: { version: 0 } });
+            // @ts-expect-error - bare boolean at root must be a TS error
+            new Mirror({ doc, initialState: { active: true } });
+            // Allowed: containers (object/array/string), null, undefined
+            new Mirror({
+                doc: new LoroDoc(),
+                initialState: {
+                    list: [],
+                    text: "hi",
+                    map: { a: 1 },
+                    absent: null,
+                    also: undefined,
+                },
+            });
+        };
+        expect(_typeChecks).toBeDefined();
+    });
+
+    it("throws when initialState contains a boolean at the root (no schema)", () => {
+        const doc = new LoroDoc();
+        expect(
+            () =>
+                new Mirror({
+                    doc,
+                    initialState: { isActive: true } as any,
+                }),
+        ).toThrow(/initialState\["isActive"\].*root/i);
+    });
+
+    it("throws when initialState contains a primitive at the root (with schema)", () => {
+        const doc = new LoroDoc();
+        const badSchema = schema({
+            // Bypass type-level constraint to simulate runtime misuse.
+            version: schema.Number() as any,
+            notes: schema.LoroList(schema.LoroMap({})),
+        } as any);
+        expect(
+            () =>
+                new Mirror({
+                    doc,
+                    schema: badSchema,
+                    initialState: { version: 0, notes: [] } as any,
+                }),
+        ).toThrow(/initialState\["version"\].*root/i);
+    });
+
+    it("ignores null/undefined root values in initialState", () => {
+        const doc = new LoroDoc();
+        const mirror = new Mirror({
+            doc,
+            initialState: {
+                missing: null,
+                absent: undefined,
+                notes: [],
+            } as any,
+        });
+        expect(doc.toJSON()).toStrictEqual({ notes: [] });
+        expect(mirror.getState()).toMatchObject({ notes: [] });
+    });
+
     it("getContainerIds returns all registered container IDs for complex nested structures", async () => {
         const doc = new LoroDoc();
 

packages/jotai/src/index.ts

@@ -14,6 +14,7 @@ import type {
     SchemaType,
     InferType,
     InferInputType,
+    RootInitialValue,
 } from "loro-mirror";
 
 type MirrorUpdateSource = "LORO" | "MIRROR" | "EPHEMERAL";
@@ -33,9 +34,14 @@ export interface LoroMirrorAtomConfig<S extends SchemaType> {
     schema: S;
 
     /**
-     * Initial state (optional)
+     * Initial state (optional). Root entries must be container-shaped
+     * (objects, arrays, strings, or `null`/`undefined`); bare numbers and
+     * booleans are rejected, since LoroDoc only stores containers at the
+     * document root.
      */
-    initialState?: Partial<InferInputType<S>>;
+    initialState?: Partial<InferInputType<S>> & {
+        [key: string]: RootInitialValue;
+    };
 
     /**
      * Whether to validate state updates against the schema

packages/react/src/hooks.tsx

@@ -16,6 +16,7 @@ import {
     SchemaType,
     Mirror,
 } from "loro-mirror";
+import type { RootInitialValue } from "loro-mirror";
 import type { LoroDoc, EphemeralStore } from "loro-crdt";
 // (No external state helper needed; Mirror handles Immer internally)
 
@@ -34,9 +35,14 @@ export interface UseLoroStoreOptions<S extends SchemaType> {
     schema: S;
 
     /**
-     * Initial state (optional)
+     * Initial state (optional). Root entries must be container-shaped
+     * (objects, arrays, strings, or `null`/`undefined`); bare numbers and
+     * booleans are rejected, since LoroDoc only stores containers at the
+     * document root.
      */
-    initialState?: Partial<InferInputType<S>>;
+    initialState?: Partial<InferInputType<S>> & {
+        [key: string]: RootInitialValue;
+    };
 
     /**
      * Whether to validate state updates against the schema