# 前端可视化库设计方案 (`@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**：设计开放的注册接口，允许第三方开发者注册自定义渲染器。
    ```typescript
    // 允许用户注册自定义渲染器，支持“主题市场”商业化
    VizRegistry.register('GraphTracer', CyberpunkGraphRenderer);
    ```
- **中间件机制**：允许拦截和修改指令流，实现自定义的逻辑增强（如增加声音音效）。

## 4. 预期形态
该库将发布为 NPM 包，提供如下使用方式：

```typescript
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)。