task.md

2026-03-04 v1.5.13 - Tauri Migration Task Consolidation

English Document

Priority Task Snapshot

• Bridge-first migration baseline is active (Tauri + Node sidecar + Godot Path Mode).
• Runtime path adaptation has been integrated for sidecar and frontend data roots.
• Worker runtime resolution has been stabilized for packaged sidecar scenarios.
• Existing-cache prompt parity in Tauri load flow needs final strict regression confirmation.
• Duplicate load execution guard needs final verification across startup/reconnect scenarios.
• Godot history tracking for center-switch actions needs final acceptance checks.
• Final Electron decommission readiness checklist remains pending.

Current Acceptance Targets

1. Exactly one prompt for cache decision when cache exists.
2. Exactly one load/build/restore execution per user-triggered load.
3. Stable websocket lifecycle without startup churn side effects.
4. History panel records central-node switches from Godot interactions.
5. Tauri desktop + Android path documented with Capacitor coexistence strategy.

中文文档

当前任务快照

• Bridge-first 迁移基线已启用（Tauri + Node sidecar + Godot Path Mode）。
• Sidecar 与前端数据根路径的运行时适配已集成。
• 打包 Sidecar 场景下的 Worker 路径解析已稳定。
• Tauri 加载流程中“缓存已存在提示”一致性仍需最终严格回归确认。
• 重复加载执行防护仍需在启动/重连场景下完成最终验证。
• Godot 中心切换动作的 History 记录仍需最终验收。
• Electron 下线前最终就绪清单仍待完成。

当前验收目标

1. 缓存存在时只出现一次选择提示。
2. 每次用户触发加载仅执行一次 load/build/restore。
3. WebSocket 生命周期稳定，无启动抖动副作用。
4. Godot 交互触发的中心节点切换可写入 History 面板。
5. Tauri 桌面与 Android 路径具备文档化说明，并与 Capacitor 共存策略一致。

---

Task: Refining Path Mode Visualization

• Critical Bug Fix
  • Fix Navigation Failure: Tree View defaulting to linear mode on switch center. Ensure treeLayout is generated during switchCenter.
• Data Consistency (Frontend)
  • Ensure inDegree is correctly calculated and passed in payload.
    • Ensure inDegree is correctly calculated and passed in payload.
    • Godot: Implement Lazy Loading Visualization
    • Backend: Update path_core.js to allow unrestricted context expansion for forcedExpansionSet.
    • Frontend Bridge: Update path_app.js to handle forcedExpansionNodes and pass to worker.
    • Simplify Lazy Loading UI (Godot)
    • Update tree_renderer.gd:
      • Remove separate (+)/(-) buttons.
      • Implement unified [ Count ] button (circle with number).
      • Button toggles forcedExpansion state.
      • Default state is collapsed.
    • Ensure path_app.js handles the toggle correctly (reusing existing logic).
    • Godot Renderer: Update tree_renderer.gd to calculate visible In-Degree and show (+)/(-) buttons.
    • Godot Signals: Wire up expand/collapse signals through tree_view_panel, path_mode_ui to ws_client.
      • (Godot) Implement logic to verify Visible < Global In-Degree to show (+).
• Tree View Visual & Interaction Overhaul
  • Visual Cleanup (Godot)
    • Remove (+)/(-) and [Count] buttons from tree_renderer.gd.
    • Remove separate click areas for these buttons.
  • Interaction Update (Godot)
    • Double Click: Change to Toggle Expansion (Emit expand/collapse).
    • Right Click: Toggle Expansion (Same as Dbl Click).
    • Middle Click: Collapse All (Emit new signal collapse_all_requested).
    • Long Press: Implement Navigation (Switch Central).
      • Add _process check for hold duration.
      • Draw Progress Ring during hold.
      • Trigger navigation on completion.
  • Focus Mode (Godot)
    • Add "Focus on this node" checkbox to settings_panel.tscn.
    • Implement focus_node_id state in tree_renderer.gd (visual only for now).
    • Update _draw to dim nodes/edges not connected to focus_node_id when enabled.
  • Backend Updates
    • Add collapseAll handler in path_app.js.
• Tree Renderer Update (Godot)
  • In-Degree Display: Add visualization for in-degree (e.g., small badge/number).
  • Last Node Button: Hide expand button for the last node in the chain (target node).
  • Bezier Aesthetics:
    • Implement edge filtering to avoid skip-level connections.
• Frontend UI Fixes (Electron)
  • Fix In-Degree Mismatch: Investigate and correct the data source for In-Degree numbers in the details panel.
  • Fix Resizing Layout: Ensure Incoming/Outgoing columns resize proportionally with the window.
  • Edge Visibility: Modify renderer to hide edges by default and only show on hover/click.
  • In-Degree Display Setting: Add setting to toggle between Visible/Total count (Default: Visible).
• Data Validation
  • Disable Path Mode if No Data: Prevent clicking "Path Mode" button if graphData is empty/undefined.
  • Fix False Negative: Ensure graphData check correctly detects dynamically loaded data in Mini Build mode.
  • Inline Feedback: Replace alert() with a text message next to the button.
• Fix Godot Script Errors
  • TreeRenderer Parse Error: Add class_name TreeRenderer to tree_renderer.gd or fix syntax error causing parse failure.
• Fix Tree View Interactions
  • Fix Right-Click Toggle: Ensure right-click (and double-click) correctly toggles between Expand and Collapse based on current state.
  • Fix Collapse All:
    • Debug Middle Click binding.
    • Add visible "Collapse All" button to UI.
• Fix Regression Errors:
  • Restore _is_pressed and collapse_all_requested in tree_renderer.gd.
• Verification
  • Verify "Expand" button appears for nodes with hidden parents.
  • Verify clicking "Expand" reveals "Fair Value" or similar missing nodes.

v1.4.2 - Spine & Tributaries Layout

• Core Algorithm Implementation (path_core.js)
  • Data Structure: Implement Spine identification (Main Path).
  • Slot Manager: Create Y-Axis Allocator to manage vertical slots per X-column.
  • Layout Logic:
    • Place Spine nodes at Y=0.
    • Place Tributaries (Prerequisites) laterally using "Preceding Parent" priority.
    • Ensure Stationary Expansion (Expanding a node does not shift the Spine).
• Frontend Integration
  • Verify switchCenter triggers correct layout recalculation.
  • Test with complex graphs to ensure no overlapping nodes.

---

任务：完善路径模式可视化 (Task: Refining Path Mode Visualization)

• 关键 Bug 修复 (Critical Bug Fix)
  • 修复导航失败: 树状视图在切换中心时默认为线性模式。确保在 switchCenter 期间生成 treeLayout。
• 数据一致性 (前端)
  • 确保在有效负载中正确计算并传递 inDegree。
    • 确保在有效负载中正确计算并传递 inDegree。
    • Godot: 实现懒加载可视化
    • 后端: 更新 path_core.js 以允许 forcedExpansionSet 的无限制上下文扩展。
    • 前端桥接: 更新 path_app.js 以处理 forcedExpansionNodes 并传递给 Worker。
    • 简化懒加载 UI (Godot)
    • 更新 tree_renderer.gd:
      • 移除单独的 (+)/(-) 按钮。
      • 实现统一的 [ 计数 ] 按钮（带数字的圆圈）。
      • 按钮切换 forcedExpansion 状态。
      • 默认状态为折叠。
    • 确保 path_app.js 正确处理切换（重用现有逻辑）。
    • Godot 渲染器: 更新 tree_renderer.gd 以计算可见入度并显示 (+)/(-) 按钮。
    • Godot 信号: 通过 tree_view_panel、path_mode_ui 将 expand/collapse 信号连接到 ws_client。
      • (Godot) 实现逻辑以验证 可见 < 全局入度 以显示 (+)。
• 树状视图视觉与交互重修
  • 视觉清理 (Godot)
    • 从 tree_renderer.gd 中移除 (+)/(-) 和 [Count] 按钮。
    • 移除这些按钮的单独点击区域。
  • 交互更新 (Godot)
    • 双击: 更改为切换扩展（发射 expand/collapse）。
    • 右键单击: 切换扩展（与双击相同）。
    • 中键单击: 全部折叠（发射新信号 collapse_all_requested）。
    • 长按: 实现导航（切换中心）。
      • 添加 _process 检查保持持续时间。
      • 在保持期间绘制进度环。
      • 完成时触发导航。
  • 专注模式 (Godot)
    • 向 settings_panel.tscn 添加“聚焦于此节点”复选框。
    • 在 tree_renderer.gd 中实现 focus_node_id 状态（目前仅视觉）。
    • 更新 _draw 以在启用时调暗未连接到 focus_node_id 的节点/边缘。
  • 后端更新
    • 在 path_app.js 中添加 collapseAll 处理程序。
• 树渲染器更新 (Godot)
  • 入度显示: 添加入度可视化（例如，小徽章/数字）。
  • 最后一个节点按钮: 隐藏链中最后一个节点（目标节点）的展开按钮。
  • 贝塞尔美学:
    • 实现边缘过滤以避免跳级连接。
• 前端 UI 修复 (Electron)
  • 修复入度不匹配: 调查并更正详细信息面板中入度数字的数据源。
  • 修复布局调整大小: 确保传入/传出列随窗口按比例调整大小。
  • 边缘可见性: 修改渲染器以默认隐藏边缘，仅在悬停/点击时显示。
  • 入度显示设置: 添加设置以在可见/总数之间切换（默认：可见）。
• 数据验证
  • 这也是如果无数据则禁用路径模式: 如果 graphData 为空/未定义，防止点击“路径模式”按钮。
  • 修复误报: 确保 graphData 检查正确检测 Mini Build 模式下的动态加载数据。
  • 内联反馈: 用按钮旁边的文本消息替换 alert()。
• 修复 Godot 脚本错误
  • TreeRenderer 解析错误: 向 tree_renderer.gd 添加 class_name TreeRenderer 或修复导致解析失败的语法错误。
• 修复树状视图交互
  • 修复右键切换: 确保右键单击（和双击）根据当前状态正确在展开和折叠之间切换。
  • 修复全部折叠:
    • 调试中键绑定。
    • 向 UI 添加可见的“全部折叠”按钮。
• 修复回归错误:
  • 恢复 tree_renderer.gd 中的 _is_pressed 和 collapse_all_requested。
• 验证
  • 验证“展开”按钮是否出现在具有隐藏父节点的节点上。
  • 验证点击“展开”是否显示“公允价值”或类似的缺失节点。

v1.4.2 - 主干与支流布局 (Spine & Tributaries Layout)

• 核心算法实施 (path_core.js)
  • 数据结构: 实现 Spine 识别（主路径）。
  • 插槽管理器: 创建 Y轴分配器 以管理每个 X 列的垂直插槽。
  • 布局逻辑:
    • 将主干节点放置在 Y=0。
    • 使用“先前父节点”优先级横向放置支流（前置节点）。
    • 确保 静态展开 (展开节点不移动主干)。
• 前端集成
  • 验证 switchCenter 触发正确的重新布局计算。
  • 使用复杂图表测试以确保没有节点重叠。

v1.4.3 - 9-Rule Tree Layout Engine (2026-02-26)

• Core Algorithm: Ownership System (path_core.js)
  • Step 1: Add expansionOrder parameter to getTreeLayout()
  • Step 2: Add currentOwner, ownerPriority, _isOnSpine to layout nodes
  • Step 3: Implement tryClaim() with 9 rules
  • Step 4: Implement determineVisibility() + isOwnerChainVisible()
  • Step 5: Filter edges by ownership (Rule 5)
  • Step 6: Group hulls by ownership
• Frontend Bridge (path_app.js)
  • Step 7: Convert forcedExpansionNodes Set → expansionOrder Array
  • Step 8: Add stickyClaimEnabled setting
• Godot Renderer (tree_renderer.gd)
  • Step 9: Edge filtering by currentOwner
  • Step 10: Hull collision avoidance
  • Step 11: Node type coloring (spine/tributary/shared/migrated)
  • Step 12: Expansion indicator badge
• Worker (path_worker.js)
  • Step 13: Pass expansionOrder + stickyClaimEnabled to getTreeLayout()
• Verification
  • Test Rule 2 (Preceding Immunity)
  • Test Rule 3 (Following Migration)
  • Test Rule 6 (Spine Always Visible)
  • Test Rule 7 (Sticky Claim toggle)
  • Test hull-node collision avoidance

---

v1.4.3 - 9 规则树形布局引擎 (2026-02-26)

• 核心算法：所有权系统 (path_core.js)
  • 步骤 1: 向 getTreeLayout() 添加 expansionOrder 参数
  • 步骤 2: 向布局节点添加 currentOwner, ownerPriority, _isOnSpine
  • 步骤 3: 实现包含 9 条规则的 tryClaim()
  • 步骤 4: 实现 determineVisibility() + isOwnerChainVisible()
  • 步骤 5: 按所有权过滤边（规则 5）
  • 步骤 6: 按所有权分组 hull
• 前端桥接 (path_app.js)
  • 步骤 7: 将 forcedExpansionNodes Set 转为 expansionOrder Array
  • 步骤 8: 添加 stickyClaimEnabled 设置
• Godot 渲染器 (tree_renderer.gd)
  • 步骤 9: 按 currentOwner 过滤边
  • 步骤 10: Hull 碰撞避让
  • 步骤 11: 节点类型着色（脊柱/支流/共享/迁移）
  • 步骤 12: 展开指示器徽章
• Worker (path_worker.js)
  • 步骤 13: 传递 expansionOrder + stickyClaimEnabled
• 验证
  • 测试规则 2（前置免疫）
  • 测试规则 3（后续迁移）
  • 测试规则 6（脊柱始终可见）
  • 测试规则 7（粘性认领开关）
  • 测试 hull-节点碰撞避让