Feat: LoroTree (#16)

* feat: tree support init

* docs: tree

* fix: tree apply

* refactor: refine a few details

* fix: a few more errors

* fix: get parent key node correctly for tree

* fix(core): assign TreeIDs via onCreate and patch child parent in batch creates

- Add onCreate callback to tree-create changes (diff.ts) to:
    - write the assigned TreeID back into the new state node
    - retarget queued child creates’ parent to the freshly created parent ID
- Apply tree creates in order and invoke onCreate immediately after createNode (mirror.ts)
to ensure children receive the correct parent ID in the same update
- Document Tree create ordering & IDs in README with example (incl. Chinese note)
- Improve type checks: isValueOfContainerType recognizes array shapes for List/Tree (utils.ts)
- Add comments and optional debug divergence check for Tree updates (mirror.ts)
- Update tests for tree behavior and quoting consistency

Rationale: users cannot know new TreeIDs ahead of time; when creating a parent and its children
together, the parent’s ID is unknown at diff time. The onCreate hook backfills IDs and patches
child parent references to keep state and Loro in sync without rebuilding entire subtrees.

* test: add loro tree fuzzing tests

Author: zxch3n

.eslintrc.js

@@ -4,7 +4,7 @@
         "suspicious": "warn"
     },
     "rules": {
-        "typescript/no-explicit-any": "error",
+        "typescript/no-explicit-any": "warn",
         "typescript/no-unsafe-type-assertion": "off"
     },
     "overrides": [

.oxlintrc.json

@@ -0,0 +1,161 @@
+# Implementation Plan: LoroTree Support in Mirror
+
+Status: Completed • Owner: Core • Last updated: 2025-08-28
+
+## Goals
+
+- Provide first-class LoroTree support in Mirror for bidirectional sync between app state and loro-crdt Tree containers.
+- Maintain parity with existing Map/List/Text/MovableList flows, including schema validation and event-driven state updates.
+
+## Non-Goals
+
+- Rich tree-aware UIs (out of scope, Mirror focuses on sync/state).
+- Automatic inference of Tree from plain arrays without schema.
+
+## Current Gaps (as-is)
+
+- Mirror has no Tree handling in: root init, nested registration, read path, or write path.
+- loroEventApply does not apply `tree` diffs; path walker cannot resolve nodes by id within arrays.
+- diff does not compute structural Tree diffs.
+- Schema lacks `loro-tree` type/guards/defaults; utils lacks `Tree` in helpers.
+
+## State Model
+
+Represent a Tree in Mirror state as nested nodes:
+
+```ts
+type TreeNode<T = Record<string, unknown>> = {
+  id: string;             // TreeID string from Loro
+  data: T;                // node metadata (validated by nodeSchema)
+  children: TreeNode[];   // ordered children
+}
+
+// Mirror state value for a LoroTree: array of roots
+type TreeValue<T> = TreeNode<T>[]
+```
+
+Notes:
+- When app creates new nodes via state, `id` may be omitted; Loro assigns it on create; events will fill it back.
+- Node data is a LoroMap schema (`nodeSchema`) for validation and nested containers.
+
+## Public Schema API Changes
+
+- Add `schema.LoroTree(nodeSchema, options?)`
+  - `type: "loro-tree"`, `getContainerType(): "Tree"`.
+  - `nodeSchema`: `LoroMapSchema<Record<string, SchemaType>>` for `node.data`.
+- `types.ts`
+  - Add `LoroTreeSchema<T>` to `SchemaType` and `ContainerSchemaType` unions.
+  - `InferType<LoroTreeSchema<T>>` resolves to `Array<{ id: string; data: InferType<T>; children: ... }>`.
+- `validators.ts`
+  - Add `isLoroTreeSchema` type guard.
+  - `validateSchema` support: top-level is `Array`; validate `node.data` recursively using `nodeSchema`; validate `children` recursively.
+  - `getDefaultValue` returns `[]` when required; else `undefined`.
+
+## Core Changes (Read Path)
+
+`loroEventApply.ts`
+- Implement `tree` diff application:
+  - Initialize target as `[]` if missing.
+  - `create`: insert `{ id, data: {}, children: [] }` at `parent/index` (root if `parent` undefined).
+  - `move`: remove from `oldParent/oldIndex` and insert at `parent/index` (if same parent and `oldIndex < index`, decrement target index).
+  - `delete`: remove subtree at `oldParent/oldIndex`.
+- Enhance path resolution to support node lookup by `id` inside arrays so map diffs to `node.data` apply cleanly:
+  - When current is an array and next segment is a string, interpret as `TreeID` string and select element with `elem.id === seg`.
+- Continue using `applyMapDiff` for `node.data` changes.
+
+## Core Changes (Write Path)
+
+`diff.ts`
+- Extend `diffContainer` to handle `ContainerType === "Tree"` with `diffTree(...)`.
+- Implement `diffTree` (structure + node data):
+  - Build old/new id->node maps and parent relationships.
+  - Deletions: nodes in old not in new (delete deepest-first to avoid orphaning).
+  - Creates: nodes in new not in old (create top-down so parents exist).
+  - Moves: common nodes whose `(parentId, index)` changed.
+  - Node data updates: for common nodes, route to `diffContainer` of `node.data` via the attached `LoroMap` container id.
+
+`mirror.ts`
+- `Change` union: add Tree operations
+  - `tree-create`: `{ container: ContainerID, kind: "tree-create", parent?: TreeID, index: number }`
+  - `tree-move`: `{ container: ContainerID, kind: "tree-move", target: TreeID, parent?: TreeID, index: number }`
+  - `tree-delete`: `{ container: ContainerID, kind: "tree-delete", target: TreeID }`
+- Initialization
+  - Include `"loro-tree"` in root container registration and `getRootContainerByType` calls.
+  - For Tree nested registration, when visiting nodes, register `node.data` container with `nodeSchema`.
+- Loro event registration
+  - For `event.diff.type === "tree"`, on `create` resolve node then `registerContainer(node.data.id, nodeSchema)`.
+- Apply changes
+  - `applyRootChanges`: support `"loro-tree"` root and forward to `updateTopLevelContainer`.
+  - `applyContainerChanges`: add `case "Tree"` to handle `tree-*` changes via `LoroTree.createNode/move/delete`.
+  - `updateTopLevelContainer`: add `"Tree"` branch to compute tree diffs and apply.
+  - `initializeContainer`: when kind `"Tree"` and initial value present, seed structure with `createNode`, then initialize each `node.data` using schema.
+  - `createContainerFromSchema`: return `[new LoroTree(), "Tree"]` for `"loro-tree"`.
+  - `getSchemaForChild`: when parent schema is `loro-tree`, return `nodeSchema` for node data.
+
+`utils.ts`
+- `getRootContainerByType`: add `"Tree" -> doc.getTree(key)`.
+- Do not infer `Tree` in `tryInferContainerType` (requires schema to avoid ambiguity with plain lists).
+
+## Tests
+
+New: `packages/core/tests/core/mirror-tree.test.ts`
+- FROM_LORO: create/move/delete in Loro updates Mirror state (`{id,data,children}`), including nested `data` updates.
+- TO_LORO: mutating state (new nodes without id, moves, deletes, data changes) updates Loro via `tree-*` changes and map updates.
+- Mixed operations in one `setState` produce consistent changes.
+- Fractional index compatible: numeric `index` passed; Loro handles ordering.
+
+## Edge Cases & Performance
+
+- Same-parent move index adjustment when `oldIndex < index`.
+- Deepest-first deletion ordering.
+- Optional in-memory index per tree during event application for O(1) node lookup (can be a follow-up optimization).
+- Concurrency handled by Loro; Mirror applies diffs idempotently.
+
+## Rollout & Verification
+
+1) Baseline
+- [x] `pnpm build && pnpm test && pnpm typecheck`
+- [ ] `pnpm lint`
+
+2) Schema & Utils
+- [x] Add `LoroTreeSchema` to `types.ts` (+ InferType)
+- [x] Add `schema.LoroTree()` to `schema/index.ts`
+- [x] Add `isLoroTreeSchema`, extend validators and defaults
+- [x] Add `Tree` to `getRootContainerByType`
+
+3) Read Path
+- [x] loroEventApply: apply `tree` diffs (create/move/delete)
+- [x] loroEventApply: path walker supports node id in arrays
+- [x] Register `node.data` containers on tree creates
+
+4) Write Path
+- [x] diff: add `Tree` branch and implement `diffTree`
+- [x] mirror: extend `Change` union with `tree-*`
+- [x] mirror: handle `case "Tree"` in `applyContainerChanges`
+- [x] mirror: update top-level container branch for `"Tree"`
+- [x] mirror: nested registration + initialization for `node.data`
+
+5) Tests
+- [x] Add `mirror-tree.test.ts` with FROM_LORO, TO_LORO, mixed flows
+- [x] Run and fix regressions
+
+6) Docs
+- [ ] README entry: Tree shape `{ id, data, children }` and schema requirements
+
+7) Final QA
+- [x] `pnpm build`
+- [x] `pnpm test`
+- [ ] `pnpm lint`
+- [x] `pnpm typecheck`
+
+## Progress Notes
+
+- Normalized tree JSON from `{ id, meta, children }` to `{ id, data, children }` during initialization for consistent state shape.
+- Scoped path remapping so only tree node `meta` is treated as `data` (does not affect root `meta` maps), fixing a regression in state.test profile.bio.
+- Initial Tree top-level updates rebuild structure; `diffTree` is implemented and can be used at root for minimal ops in a follow-up if desired.
+
+## Risks / Open Questions
+
+- Node identification in state: require `id` to match Loro `TreeID` (string). For newly created nodes without id, Mirror will create and fill id from events; interim state may temporarily show empty `id` values—acceptable for UI with optimistic updates.
+- Large tree performance: consider indexing maps for event application if profiling shows hotspots.
+- Schema composition: `nodeSchema` can itself contain containers; ensure nested registration paths are correct.

IMPLEMENTATION_PLAN.md

@@ -309,6 +309,29 @@ For detailed documentation, see the README files in each package:
 - [React Documentation](./packages/react/README.md)
 - [Jotai Documentation](./packages/jotai/README.md)
 
+## Schema Overview
+
+Loro Mirror uses a typed schema to map your app state to Loro containers. Common schema constructors:
+
+- `schema.String(options?)`: string
+- `schema.Number(options?)`: number
+- `schema.Boolean(options?)`: boolean
+- `schema.Ignore(options?)`: exclude from sync (app-only)
+- `schema.LoroText(options?)`: rich text (`LoroText`)
+- `schema.LoroMap(definition, options?)`: object (`LoroMap`)
+- `schema.LoroList(itemSchema, idSelector?, options?)`: list (`LoroList`)
+- `schema.LoroMovableList(itemSchema, idSelector, options?)`: movable list that emits move ops (requires `idSelector`)
+- `schema.LoroTree(nodeSchema, options?)`: hierarchical tree (`LoroTree`) with per-node `data` map
+
+Tree nodes have the shape `{ id?: string; data: T; children: Node<T>[] }`. Define a tree by passing a node `LoroMap` schema:
+
+```ts
+import { schema } from "loro-mirror";
+
+const node = schema.LoroMap({ title: schema.String({ required: true }) });
+const mySchema = schema({ outline: schema.LoroTree(node) });
+```
+
 ## API Reference (Core Mirror)
 
 ### Mirror

README.md

@@ -409,6 +409,119 @@ const mySchema = schema({
 - `schema.LoroText(options?)` - Loro rich text
 - `schema.LoroMap(definition, options?)` - Loro map (object)
 - `schema.LoroList(itemSchema, idSelector?, options?)` - Loro list (array)
+- `schema.LoroMovableList(itemSchema, idSelector, options?)` - Loro movable list that emits stable move operations when order changes (requires an `idSelector`).
+- `schema.LoroTree(nodeSchema, options?)` - Loro tree where each node carries a `data` map described by `nodeSchema`.
+
+### Tree Schema
+
+Tree fields let you model hierarchical data with per-node metadata stored in a Loro map.
+
+Shape in app state:
+
+```ts
+type TreeNode<T> = {
+  id?: string; // optional when creating; assigned by Loro if omitted
+  data: T;     // validated by the provided nodeSchema
+  children: Array<TreeNode<T>>;
+};
+```
+
+Define a tree by providing a node `LoroMap` schema. Each node's `data` will follow that schema; `children` is always an array of nodes.
+
+```ts
+import { schema } from "loro-mirror";
+
+const folderNode = schema.LoroMap({
+  name: schema.String({ required: true }),
+  color: schema.String({ defaultValue: "blue" }),
+});
+
+const fsSchema = schema({
+  tree: schema.LoroTree(folderNode),
+});
+
+// Example initial state
+const initial = {
+  tree: [
+    {
+      data: { name: "root" },
+      children: [
+        { data: { name: "docs" }, children: [] },
+        { data: { name: "src" }, children: [] },
+      ],
+    },
+  ],
+};
+```
+
+Notes:
+
+- `id` is optional when creating nodes. Mirror will create the node in the Loro tree and use its generated ID. If you supply an existing ID, Mirror will target that node.
+- Reordering or moving nodes is done by changing the `children` arrays. Mirror diffs trees and applies minimal `create`/`move`/`delete` operations, and syncs nested `data` map changes.
+- Under the hood, Loro serializes node payloads under `meta`. Mirror normalizes it to `data` in app state and schema validation.
+
+#### Updating Trees with `setState`
+
+Use normal `setState` updates; mutate the draft tree and Mirror will apply the minimal tree operations.
+
+Add nodes:
+
+```ts
+// Add a root-level node
+store.setState((s) => {
+  s.tree.push({ data: { name: "assets" }, children: [] });
+});
+
+// Add a child under an existing parent (by index here)
+store.setState((s) => {
+  const parent = s.tree[0];
+  parent.children.push({ data: { name: "images" }, children: [] });
+});
+```
+
+Update node data:
+
+```ts
+store.setState((s) => {
+  const node = s.tree[0].children[0];
+  node.data.name = "imgs"; // edits sync via the node's LoroMap
+});
+```
+
+Move or reorder nodes (same parent):
+
+```ts
+store.setState((s) => {
+  // Move last root node to the front
+  const [n] = s.tree.splice(s.tree.length - 1, 1);
+  s.tree.splice(0, 0, n);
+});
+```
+
+Move nodes across parents:
+
+```ts
+store.setState((s) => {
+  const from = s.tree[0].children;
+  const to = s.tree[1].children;
+  const [n] = from.splice(0, 1);
+  to.splice(0, 0, n);
+});
+```
+
+Delete nodes:
+
+```ts
+store.setState((s) => {
+  // Remove first child of first root node
+  s.tree[0].children.splice(0, 1);
+});
+```
+
+Tips:
+
+- Node `id`s are populated by Loro when created. If you don’t specify an `id`, it becomes available on the next state after sync; avoid relying on the new `id` inside the same `setState` call.
+- For finding nodes by `id`, traverse `s.tree` recursively and mutate the located node/children array.
 
 ### `createStore`