structrail-design/.trae/documents/visualization-library-design.md

前端可视化库设计方案 (@structrail/viz)

1. 核心目标

• 解耦：将 Tracer SDK（数据生成）与前端渲染逻辑（数据展示）完全分离。
• 复用：打造一个通用的、可嵌入的算法可视化库，服务于 StructRail 平台及第三方场景（博客、文档、IDE 插件）。
• 标准：作为 Tracer Protocol 的标准消费者，建立可视化渲染的事实标准。

2. 架构设计：确定性状态机 (Deterministic State Machine)

采用 Player + Store + Renderer 的分层架构，确保时间旅行（Time Travel）的可靠性。

2.1 Player (播放器/控制器)

• 职责：解析 JSON 指令流，控制时间轴（Play, Pause, Seek, Speed）。
• 特性：
  • 维护当前帧索引 currentIndex。
  • 支持步进（Step）和连续播放。
  • 处理“自动暂停”指令（如 tracer.wait()）。

2.2 Store (状态仓库/沙盒)

• 职责：维护“影子内存”（Shadow Memory），根据指令计算数据结构状态。
• 机制：
  • 增量计算：基于 immer.js 或类似机制，只存储指令序列和初始状态，通过重放（Replay）或关键帧（Keyframe）技术快速计算任意时刻的状态。
  • 快照 (Snapshot)：向渲染层提供只读的、标准化的数据快照。
  • State(t) = Apply(InitialState, Events[0...t])

2.3 Renderer (渲染器/组件库)

• 职责：纯 UI 展示层，遵循 UI = Render(State) 原则。
• 实现：
  • DOM/SVG 渲染器：用于常规数据结构（数组、链表、树），支持 CSS 动画和高质量文本渲染。
  • Canvas/WebGL 渲染器：用于大规模数据（如 10w+ 节点的图、矩阵热力图）。
• 组件化：提供 <ArrayVisualizer>, <GraphVisualizer> 等独立组件。

3. 关键技术挑战与策略 (Advanced Technical Considerations)

为了确保该库能适应复杂的互联网环境（移动端、嵌入式、高性能场景），需重点关注以下方面：

3.1 响应式与移动端适配 (Responsive & Mobile First)

• 自适应布局：Renderer 需具备流式布局能力。例如 ArrayVisualizer 在窄屏（手机/VS Code 侧边栏）下应自动切换为“折行显示”或“垂直列表模式”，避免横向滚动。
• 触控交互：设计移动端友好的交互模式（如长按代替 Hover，双指缩放代替滚轮）。

3.2 样式隔离与嵌入性 (Style Isolation)

• Shadow DOM：推荐使用 Web Components (Shadow DOM) 封装渲染器，彻底隔离宿主页面（如博客全局 CSS）的样式干扰。
• CSS Modules / CSS-in-JS：作为备选方案，确保类名哈希化，防止污染宿主环境。

3.3 性能降级与 LOD (Level of Detail)

• 自动后端切换：根据数据规模动态选择渲染后端。
  • 节点 < 500：使用 SVG（交互性好，调试方便）。
  • 节点 > 500：自动降级为 Canvas/WebGL（高性能）。
• LOD 策略：在缩放或快速播放时，自动隐藏非关键细节（如节点文本、阴影），保证渲染帧率。

3.4 状态序列化与分享 (Serialization)

• State Export：支持将当前 Store 的状态快照导出为 JSON。
• Deep Link：支持将状态编码为 URL 参数（如 ?state=base64...），实现“分享当前步骤”功能。

3.5 插件系统与扩展性 (Plugin System)

• Renderer Provider：设计开放的注册接口，允许第三方开发者注册自定义渲染器。

  // 允许用户注册自定义渲染器，支持“主题市场”商业化
  VizRegistry.register('GraphTracer', CyberpunkGraphRenderer);
  

• 中间件机制：允许拦截和修改指令流，实现自定义的逻辑增强（如增加声音音效）。

4. 预期形态

该库将发布为 NPM 包，提供如下使用方式：

import { Player, ArrayVisualizer } from '@structrail/viz';
import '@structrail/viz/dist/style.css'; // 或自动注入 Shadow DOM 样式

// 1. 初始化播放器
const player = new Player(events);

// 2. 渲染组件 (React 示例)
function App() {
  const snapshot = usePlayerSnapshot(player);
  
  return (
    <div className="viz-container">
      <ArrayVisualizer 
        model={snapshot.tracers['array-1']} 
        theme="cyberpunk" // 支持主题切换
      />
      <Controls player={player} />
    </div>
  );
}

5. 商业化结合点

• 开源核心：建立协议标准，获取流量。
• 付费扩展：
  • 高级主题包：赛博朋克、手绘风、企业定制皮肤。
  • 高性能渲染器：3D 图算法渲染、大数据分析引擎。
  • 云端服务：高清视频导出 (MP4/GIF)。