refactor: 全面重构 JsonTools 页面，采用声明式响应架构并统一 shadcn 样式

pages/JsonTools/types.ts

@@ -1,29 +1,55 @@
 export type DiffType = 'added' | 'removed' | 'modified' | 'unchanged';
-
 export interface DiffNode {
-  /** 节点键名（数组项为索引字符串） */
+  /** 节点键名（对象属性名，或者数组的索引字符串 "0", "1"...） */
   key: string;
-  /** 差异类型 */
+
+  /** 差异状态机核心分类 */
   type: DiffType;
-  /** 左侧值 */
-  oldValue?: unknown;
-  /** 右侧值 */
-  newValue?: unknown;
-  /** 子节点（对象或数组时存在） */
+
+  /** * 左侧原始数值快照
+   * 💡 优化点：移除了不安全的可选 ?，如果完全缺失则严格流出 undefined，
+   * 倒逼下游渲染层必须做出明确的条件分支防护。
+   */
+  oldValue: unknown;
+
+  /** 右侧最新数值快照 */
+  newValue: unknown;
+
+  /** * 子节点差异列表
+   * 💡 强类型化：只有当对象或数组这类容器节点发生比对时存在，未选中时默认为空数组 []
+   */
   children?: DiffNode[];
-  /** 完整路径，用于导航定位 */
+
+  /** * 节点的绝对路径表达式（严格遵循高可靠的 JSONPath 规约，如 "$.user.profile" 或 "$.list[0]"）
+   * 用于 DiffNavigator 差异导航条进行秒级的 scrollIntoView 视图精准定位高亮
+   */
   path: string;
-  /** 是否为叶子节点（原始值） */
+
+  /** 是否为叶子节点（若为 true 代表当前值为基本基元数据类型，若为 false 代表当前值为大括号或方括号容器） */
   isLeaf: boolean;
+
+  /**
+   * 💡 性能调优大闸（Computed Guard）：
+   * 预计算状态：代表当前节点的深层子孙节点中，是否存在任意一处 'added' | 'removed' | 'modified' 差异行为。
+   * 这使得外界的 JsonTree 在高频折叠/展开时，能在一帧之内直接通过此属性判断是否需要高亮其父大括号，
+   * 彻底终结了原先命令式深度递归遍历子树的昂贵性能代价！
+   */
+  hasDiffInChildren: boolean;
 }
 
+/** 视图对照渲染模式：sideBySide (双栏对照折叠树) | unified (单栏行级混合拍平) */
 export type ViewMode = 'sideBySide' | 'unified';
 
 export interface DiffResult {
-  /** 根节点差异树 */
+  /** 经过深层比对算法推导生成的根节点核心差异树（AST） */
   root: DiffNode;
-  /** 所有差异节点路径列表（用于导航） */
+
+  /** * 扁平化的高精度差异节点绝对路径映射表。
+   * 里面严格存储了所有 type !== 'unchanged' 的节点 path。
+   * 专供外部的 DiffNavigator (差异控制条) 充当中央路由索引，实现 0 延迟的上一处/下一处无缝切流。
+   */
   diffPaths: string[];
-  /** 差异总数 */
+
+  /** 差异核心总计数（等价于 diffPaths.length），注入 tabular-nums 配合渲染 */
   diffCount: number;
 }