feat:1.4.0 (c)

- **相较 1.3.x：`applyEditWithDiff(...)` 现在优先保证有界、可预期**
  - 细粒度 diff 精化现在受全局预算约束（比较数 / 锚点 / op / 子树规模 / wall-clock），一旦继续细化不划算，就会直接退化为 coarse splice 或保守整树 diff。
  - 预算超限属于正常控制流，不再表现为“精化过程像异常一样失败”；对接入方来说，拿到的是稳定的保守 diff，而不是额外的异常形态。
  - 当这次编辑实际命中增量路径时，root 级精细 diff 会先局部化到增量 dirty window，而不是继续对整棵 root tree 细化。
- **相较 1.3.x：保守 diff 的语义更清晰**
  - 当调用方能提供完整快照长度时，整树保守 fallback 现在会报告整文档 dirty span，避免在无 position 回退场景下把脏区误报得过小。
  - 默认 `diffRefinementDepthCap` 已调低，深层嵌套 diff 会更早退化，极端树输入下的行为也更一致。

Author: chiba233

CHANGELOG.md

@@ -7,10 +7,12 @@
 - **Compared with 1.3.x: incremental integration is now stable**
   - `parseIncremental`, `updateIncremental`, `tryUpdateIncremental`, and `createIncrementalSession` are now presented as stable integration surfaces rather than provisional internals.
   - Session fallback behavior and diff payload expectations are now treated as versioned guarantees for host applications.
-- **Compared with 1.3.x: large or deeply nested edits are more predictable to integrate**
-  - Incremental updates and `applyEditWithDiff(...)` now behave more conservatively when fine-grained refinement would be too costly or unsafe.
-  - The default `diffRefinementDepthCap` is now lower, so deep nested diff refinement degrades to coarse splice ops earlier by default.
-  - For downstream consumers, this means fewer surprising edge-case failures and clearer upgrade expectations around fallback behavior.
+- **Compared with 1.3.x: `applyEditWithDiff(...)` now prefers bounded, predictable diff behavior**
+  - Fine-grained diff refinement is now budgeted (`compare` / `anchor` / `op` / subtree-size / wall-clock caps) and degrades directly to coarse splice or conservative whole-tree diff when the cost stops being worthwhile.
+  - When the edit stays on the incremental path, root-level fine diff is localized to the incremental dirty window instead of continuing to refine the entire root tree.
+- **Compared with 1.3.x: conservative diff semantics are clearer**
+  - Whole-tree conservative fallback now reports whole-document dirty spans when the caller provides full snapshot lengths, avoiding misleadingly small dirty-span reports in no-position fallback cases.
+  - The default `diffRefinementDepthCap` is lower, so deeply nested refinement degrades earlier by default and extreme trees behave more consistently across edits.
 - **Upgrade note**
   - No breaking public API changes in `1.4.0`.
   - Existing `1.3.x` integrations can upgrade directly to `1.4.x`.

CHANGELOG.zh-CN.md

@@ -7,10 +7,12 @@
 - **相较 1.3.x：增量集成现在已进入 stable**
   - `parseIncremental`、`updateIncremental`、`tryUpdateIncremental` 与 `createIncrementalSession` 不再只是“暂时可用的内部能力”，而是可按稳定集成面理解的公开能力。
   - session 的回退语义与 diff 返回预期，现在可以按版本契约来理解和升级。
-- **相较 1.3.x：大编辑与深层结构下的行为更可预期**
-  - 当细粒度精化成本过高或存在风险时，增量更新与 `applyEditWithDiff(...)` 会更保守地选择安全路径。
-  - 默认 `diffRefinementDepthCap` 现已调低，深层嵌套 diff 会更早退化为较粗粒度的 splice。
-  - 对接入方来说，这意味着极端输入下更少的意外失败，以及更清晰的 fallback 预期。
+- **相较 1.3.x：`applyEditWithDiff(...)` 现在优先保证有界、可预期**
+  - 细粒度 diff 精化现在受全局预算约束（比较数 / 锚点 / op / 子树规模 / wall-clock），一旦继续细化不划算，就会直接退化为 coarse splice 或保守整树 diff。
+  - 当这次编辑实际命中增量路径时，root 级精细 diff 会先局部化到增量 dirty window，而不是继续对整棵 root tree 细化。
+- **相较 1.3.x：保守 diff 的语义更清晰**
+  - 当调用方能提供完整快照长度时，整树保守 fallback 现在会报告整文档 dirty span，避免在无 position 回退场景下把脏区误报得过小。
+  - 默认 `diffRefinementDepthCap` 已调低，深层嵌套 diff 会更早退化，极端树输入下的行为也更一致。
 - **升级说明**
   - `1.4.0` 没有破坏性公共 API 变更。
   - 现有 `1.3.x` 集成代码可直接升级到 `1.4.x`。

GUIDE.zh-CN.md

@@ -432,7 +432,7 @@ Use these when you are not parsing once, but keeping a document alive across man
 This incremental API set is part of the stable public surface in `1.4.x`.
 In particular, session-level fallback is a documented contract rather than an exceptional edge case:
 `applyEdit(...)` / `applyEditWithDiff(...)` may return `mode: "full-fallback"` with a `fallbackReason`,
-and `sessionOptions.diffRefinementDepthCap` lets you trade nested diff granularity for cost on very deep trees.
+and diff refinement knobs now live under `sessionOptions.diff` (or per-call `applyEditWithDiff(..., diffOptions)`).
 
 - `parseIncremental(source, options?)` — build and return the **first** incremental snapshot (`IncrementalDocument`)
 - `createIncrementalSession(source, options?, sessionOptions?)` — create a **long-lived session** for repeated edits