doxum 0.1.9 → 0.1.10

package/skills/doxum-runtime/references/guide.en.md

@@ -13,12 +13,12 @@ const document = createDocument({
   initial: { tasks: { a: { title: 'Write', done: false } } },
 });
 document.update(draft => {
-  const task = draft.tasks.a;
+  const task = draft.tasks.get('a');
   if (task) task.done = !task.done;
-  draft.tasks.b = { title: 'Review', done: false };
+  draft.tasks.put('b', { title: 'Review', done: false });
   return { warnings: [] };
 });
-const done = select(document, state => state.tasks.a?.done);
+const done = select(document, state => state.tasks.get('a')?.done);
 const tasks = select(document, state => snapshot(state.tasks));
 document.subscribe(
   path => path.tasks.item('a').done,
@@ -43,20 +43,24 @@ returns its original readonly reference. Published data is not frozen. Field cop
 are not supported; mutable exports and serialization belong to application boundaries.
 
 Infer preserves optional properties and flat variant unions. Read/Draft contain
-collection tools; assign(scope, key, inferValue) handles plain replacements containing
-nested table/list/tree data.
+collection tools. Maps use explicit methods; table/list/tree overload replace for
+member and whole-container replacement. `replace(parent, key, inferValue)` handles
+plain replacement of object or variant members that contain collection data.
 
 ## Containers And Validation
 
-| Definition                       | Data          | Draft methods                                                 |
-| -------------------------------- | ------------- | ------------------------------------------------------------- |
-| map(valueSchema, { key }?)       | record        | indexing, assignment, delete                                  |
-| table(objectOrVariant, { key }?) | ids/byId      | get/has/ids/create/remove/move                                |
-| list(field, { keyOf })           | array         | get/has/ids/insert/set/remove/move/replace                    |
-| tree(field)                      | rootId?/nodes | get/has/rootId/parent/children/insert/set/remove/move/replace |
+| Definition                       | Data          | Draft methods                                             |
+| -------------------------------- | ------------- | --------------------------------------------------------- |
+| map(valueSchema, { key }?)       | record        | get/has/ids/put/remove/replace                            |
+| table(objectOrVariant, { key }?) | ids/byId      | get/has/ids/create/remove/move/replace                    |
+| list(field, { keyOf })           | array         | get/has/ids/insert/remove/move/replace                    |
+| tree(field)                      | rootId?/nodes | get/has/rootId/parent/children/insert/remove/move/replace |
 
-Read scopes expose only read methods. Map supports field/object/variant values.
-List replacement retains the addressed key. Simple arrays and strokes can be one
+Read scopes expose only read methods. Map supports field/object/variant values;
+put is an upsert and removing a missing key is a no-op. `replace(id, value)` is
+existing-only for table/list/tree, preserves table/list order, and changes only a
+tree payload. `replace(value)` replaces a whole collection. List member replacement
+retains the addressed key. Simple arrays and strokes can be one
 atomic field. Optional supports field/variant/map/list/tree. Absent differs from
 present undefined. Variant tags are readonly; change branch by whole replacement.
 
@@ -64,7 +68,7 @@ Pure synchronous functions and Standard Schema v1 validators receive original in
 They must not mutate it; successful output is ignored, with no copy or deep conversion
 check. Transform values before entering Doxum. parse(model, unknown) copies validated
 structure and shares readonly payloads; strict parse requires atomic validators.
-Branded map/table keys flow through access, symbolic paths and impact.
+Branded map/table keys flow through methods, symbolic paths and impact.
 Path callbacks describe locations, including absent entries, and compile at registration.
 React useDocumentSelector tracks actual reads and changes dependencies when branching.
 

package/skills/doxum-runtime/references/guide.zh-CN.md

@@ -13,12 +13,12 @@ const document = createDocument({
   initial: { tasks: { a: { title: 'Write', done: false } } },
 });
 document.update(draft => {
-  const task = draft.tasks.a;
+  const task = draft.tasks.get('a');
   if (task) task.done = !task.done;
-  draft.tasks.b = { title: 'Review', done: false };
+  draft.tasks.put('b', { title: 'Review', done: false });
   return { warnings: [] };
 });
-const done = select(document, state => state.tasks.a?.done);
+const done = select(document, state => state.tasks.get('a')?.done);
 const tasks = select(document, state => snapshot(state.tasks));
 document.subscribe(
   path => path.tasks.item('a').done,
@@ -37,25 +37,28 @@ object/variant 结构只接受 schema 声明的自身属性及 variant 判别字
 snapshot 只复制 schema 结构；snapshot(rawPayload) 返回原始只读引用。
 发布数据不做运行时冻结，不再支持字段 copier。需要可修改副本或序列化时由应用边界显式处理。
 
-Infer 保留 optional 属性和扁平 variant 联合。Read/Draft 带集合方法；
-含 table/list/tree 数据的整体替换使用 assign(scope, key, inferValue)。
+Infer 保留 optional 属性和扁平 variant 联合。Read/Draft 带集合方法。map 使用显式方法；
+table/list/tree 的 replace 同时支持成员和整体替换。含集合数据的 object/variant 成员
+使用 `replace(parent, key, inferValue)` 传入普通 Infer 数据。
 
 ## 容器与校验
 
-| 声明                             | 数据          | Draft 方法                                                    |
-| -------------------------------- | ------------- | ------------------------------------------------------------- |
-| map(valueSchema, { key }?)       | record        | 索引、赋值、delete                                            |
-| table(objectOrVariant, { key }?) | ids/byId      | get/has/ids/create/remove/move                                |
-| list(field, { keyOf })           | 普通数组      | get/has/ids/insert/set/remove/move/replace                    |
-| tree(field)                      | rootId?/nodes | get/has/rootId/parent/children/insert/set/remove/move/replace |
+| 声明                             | 数据          | Draft 方法                                                |
+| -------------------------------- | ------------- | --------------------------------------------------------- |
+| map(valueSchema, { key }?)       | record        | get/has/ids/put/remove/replace                            |
+| table(objectOrVariant, { key }?) | ids/byId      | get/has/ids/create/remove/move/replace                    |
+| list(field, { keyOf })           | 普通数组      | get/has/ids/insert/remove/move/replace                    |
+| tree(field)                      | rootId?/nodes | get/has/rootId/parent/children/insert/remove/move/replace |
 
-Read 只暴露读取方法。map 支持 field/object/variant。list 替换项必须保持寻址键。
+Read 只暴露读取方法。map 支持 field/object/variant；put 是 upsert，remove 缺失键是 no-op。
+table/list/tree 的 `replace(id, value)` 只替换已存在成员，保持 table/list 顺序，且 tree
+只改变 payload；`replace(value)` 替换整个集合。list 替换项必须保持寻址键。
 简单数组与笔画可作为一个原子 field。optional 支持 field/variant/map/list/tree，
 缺失与存在的 undefined 不同。variant tag 只读，通过整体替换切换分支。
 
 校验器是纯同步函数或 Standard Schema v1，直接接收原始引用且不得修改它。
 成功返回值被忽略，不复制输入，也不深度检查转换；数据转换在进入 Doxum 前完成。
-parse(model, unknown) 复制校验后的结构并共享只读 payload；严格解析要求原子字段具备校验器。品牌键贯穿 map/table 访问、
+parse(model, unknown) 复制校验后的结构并共享只读 payload；严格解析要求原子字段具备校验器。品牌键贯穿 map/table 方法、
 符号路径和 impact。路径回调描述地址，包括缺失键，订阅注册时解析。
 React useDocumentSelector 追踪实际读取，并在选择分支改变时更新依赖。
 

package/skills/doxum-runtime/references/patterns.en.md

@@ -11,7 +11,7 @@ const model = object({
 });
 ```
 
-Edit position.x, replace stroke whole, use rows.set(key, value) for keyed item edits.
+Edit position.x, replace stroke whole, and use rows.replace(key, value) for keyed item edits.
 
 ## Complex Replacement
 
@@ -21,13 +21,13 @@ const model = object({
 });
 const document = createDocument({ schema: model, initial: { entries: {} } });
 document.update(draft => {
-  assign(draft.entries, 'a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
-  draft.entries.a!.rows.get('x')!.title = 'Updated';
+  draft.entries.put('a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
+  draft.entries.get('a')!.rows.get('x')!.title = 'Updated';
 });
 ```
 
-TypeScript cannot express different read/write types for mapped properties.
-assign checks Infer replacement data and uses the same mutation session.
+Map entries use put. Use top-level replace for object/variant members whose Draft
+type contains collection tools; collection replace(next) handles whole containers.
 
 ## Domain Keys
 
@@ -45,7 +45,7 @@ const model = object({ people: map(object({ name: field(text) }), { key: personI
 const initial = parse(model, { people: { 'person:1': { name: 'Ada' } } });
 ```
 
-Brands flow through indexed access, table methods, symbolic paths and collection impact.
+Brands flow through map/table methods, symbolic paths and collection impact.
 
 ## Ordered Edits, History And Replay
 

package/skills/doxum-runtime/references/patterns.zh-CN.md

@@ -11,7 +11,7 @@ const model = object({
 });
 ```
 
-position.x 细粒度赋值；stroke 整体替换；rows.set(key, value) 按稳定键替换项。
+position.x 细粒度赋值；stroke 整体替换；rows.replace(key, value) 按稳定键替换项。
 
 ## 含集合的整体替换
 
@@ -21,13 +21,13 @@ const model = object({
 });
 const document = createDocument({ schema: model, initial: { entries: {} } });
 document.update(draft => {
-  assign(draft.entries, 'a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
-  draft.entries.a!.rows.get('x')!.title = 'Updated';
+  draft.entries.put('a', { rows: { ids: ['x'], byId: { x: { title: 'First' } } } });
+  draft.entries.get('a')!.rows.get('x')!.title = 'Updated';
 });
 ```
 
-TypeScript 映射属性不能分别指定读写类型。assign 校验对应 Infer 数据，
-经同一 mutation session 修改。
+map 条目使用 put。Draft 类型含集合方法的 object/variant 成员使用顶层 replace；
+集合整体替换使用集合自身的 replace(next)，并经同一 mutation session 修改。
 
 ## 领域键
 
@@ -45,7 +45,7 @@ const model = object({ people: map(object({ name: field(text) }), { key: personI
 const initial = parse(model, { people: { 'person:1': { name: 'Ada' } } });
 ```
 
-品牌类型贯穿索引、table 方法、符号路径和 collection impact。
+品牌类型贯穿 map/table 方法、符号路径和 collection impact。
 
 ## 顺序、History 与重放