explanatory-playground

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Explanatory Playground

解释性调试 Playground

Build dev-only visualizations that make invisible system behavior visible.

构建仅面向开发者的可视化工具，将不可见的系统行为直观呈现出来。

Workflow

工作流程

1. Clarify the target

1. 明确目标

Use AskUserQuestion to understand what needs visualization:

question: "What kind of system should the playground reveal?"
header: "System type"
options:
  - label: "State machine"
    description: "Finite states with transitions (auth flow, form wizard, game state)"
  - label: "Data flow"
    description: "Data transforming through a pipeline (API → transform → render)"
  - label: "Event system"
    description: "Publishers and subscribers, event propagation"
  - label: "Algorithm"
    description: "Step-by-step logic (sorting, pathfinding, search)"

Then ask what's confusing:

question: "What specifically is hard to understand?"
header: "Hidden aspect"
options:
  - label: "Current state"
    description: "I can't see what state the system is in right now"
  - label: "Why transitions happen"
    description: "I don't know what triggers changes or why"
  - label: "Data shape"
    description: "I can't see what the data looks like at each step"
  - label: "Timing/sequence"
    description: "Things happen too fast or in unclear order"

使用AskUserQuestion工具明确需要可视化的对象：

question: "What kind of system should the playground reveal?"
header: "System type"
options:
  - label: "State machine"
    description: "Finite states with transitions (auth flow, form wizard, game state)"
  - label: "Data flow"
    description: "Data transforming through a pipeline (API → transform → render)"
  - label: "Event system"
    description: "Publishers and subscribers, event propagation"
  - label: "Algorithm"
    description: "Step-by-step logic (sorting, pathfinding, search)"

接着询问用户具体的困惑点：

question: "What specifically is hard to understand?"
header: "Hidden aspect"
options:
  - label: "Current state"
    description: "I can't see what state the system is in right now"
  - label: "Why transitions happen"
    description: "I don't know what triggers changes or why"
  - label: "Data shape"
    description: "I can't see what the data looks like at each step"
  - label: "Timing/sequence"
    description: "Things happen too fast or in unclear order"

2. Identify what's hidden

2. 识别隐藏内容

Based on answers, determine what to surface:

State — Values that change over time
Transitions — Events that trigger changes
Relationships — How parts communicate
Logic — Conditions, thresholds, rules

根据用户的回答，确定需要展示的内容：

状态 — 随时间变化的值
转换 — 触发变化的事件
关联关系 — 各组件间的通信方式
逻辑规则 — 条件、阈值、规则

3. Pick visualization approach

3. 选择可视化方案

System	Visualization	Library
State machines	Node-edge graph	react-flow
Data flow	Directed graph / Sankey	react-flow
Events	Timeline	custom or recharts
Algorithms	Step animation	custom
Render cycles	Component tree + diffs	custom
Animations	Timeline scrubber	custom
CSS/Layout	Box model overlay	custom

See references/patterns.md for layouts, code, and implementation details.

系统类型	可视化方式	库
状态机	节点-边缘图	react-flow
数据流	有向图 / 桑基图	react-flow
事件系统	时间线	自定义或recharts
算法	步骤动画	自定义
渲染周期	组件树 + 差异对比	自定义
动画	时间线 scrubber	自定义
CSS/布局	盒模型覆盖层	自定义

查看references/patterns.md获取布局、代码和实现细节。

4. Choose interactivity level

4. 选择交互级别

Ask if unclear:

question: "How interactive should the playground be?"
header: "Interactivity"
options:
  - label: "Just show me (Recommended)"
    description: "Real-time display of state and changes"
  - label: "Let me poke around"
    description: "Click/hover to inspect details and trace origins"
  - label: "Let me trigger things"
    description: "Fire events, modify state, inject test data"
  - label: "Time travel"
    description: "Record history, scrub through past states, replay"

Level	Features	When
1 - Observe	Real-time state display	Always
2 - Inspect	Click/hover for details	Usually
3 - Manipulate	Trigger events, modify state	Edge cases
4 - Time travel	History scrubbing, replay	Race conditions

Start with 1-2. Add 3-4 when needed.

若不确定交互需求，可询问用户：

question: "How interactive should the playground be?"
header: "Interactivity"
options:
  - label: "Just show me (Recommended)"
    description: "Real-time display of state and changes"
  - label: "Let me poke around"
    description: "Click/hover to inspect details and trace origins"
  - label: "Let me trigger things"
    description: "Fire events, modify state, inject test data"
  - label: "Time travel"
    description: "Record history, scrub through past states, replay"

交互级别	功能特性	使用场景
1 - 查看	实时状态展示	所有情况
2 - 检查	点击/悬停查看详细信息	大多数情况
3 - 操作	触发事件、修改状态	边缘场景
4 - 时间回溯	记录历史、回溯过往状态、重放	竞态条件排查

建议从1-2级开始，必要时再添加3-4级功能。

6. Instrument minimally

6. 最小化埋点

Prefer event emitters (least invasive):

typescript

const debugEmitter = new EventEmitter();
function transition(from, to, event) {
  debugEmitter.emit('transition', { from, to, event, timestamp: Date.now() });
  // existing logic...
}

Use proxies for third-party code:

typescript

function observable<T extends object>(obj: T) {
  return new Proxy(obj, {
    set(target, prop, value) {
      window.dispatchEvent(new CustomEvent('state:change', {
        detail: { prop, old: target[prop], new: value }
      }));
      return Reflect.set(target, prop, value);
    }
  });
}

优先使用事件发射器（侵入性最低）：

typescript

const debugEmitter = new EventEmitter();
function transition(from, to, event) {
  debugEmitter.emit('transition', { from, to, event, timestamp: Date.now() });
  // existing logic...
}

针对第三方代码使用代理：

typescript

function observable<T extends object>(obj: T) {
  return new Proxy(obj, {
    set(target, prop, value) {
      window.dispatchEvent(new CustomEvent('state:change', {
        detail: { prop, old: target[prop], new: value }
      }));
      return Reflect.set(target, prop, value);
    }
  });
}

7. Create dev-only route

7. 创建仅面向开发者的路由

app/__dev/[system-name]/page.tsx

Guard against production:

typescript

if (process.env.NODE_ENV !== 'development') {
  return notFound();
}

app/__dev/[system-name]/page.tsx

添加生产环境防护：

typescript

if (process.env.NODE_ENV !== 'development') {
  return notFound();
}

8. Document removal

8. 记录移除步骤

Header in every created file:

typescript

/**
 * EXPLANATORY-PLAYGROUND DEBUG TOOL
 * Remove when done:
 * 1. Delete: app/__dev/[name]/page.tsx
 * 2. Delete: src/lib/[system]-debug.ts
 * 3. Remove hooks from: src/lib/[system].ts (lines XX-YY)
 * Purpose: [what this debugs]
 */

在每个创建的文件头部添加注释：

typescript

/**
 * EXPLANATORY-PLAYGROUND DEBUG TOOL
 * Remove when done:
 * 1. Delete: app/__dev/[name]/page.tsx
 * 2. Delete: src/lib/[system]-debug.ts
 * 3. Remove hooks from: src/lib/[system].ts (lines XX-YY)
 * Purpose: [what this debugs]
 */

Cleanup

清理工作

On removal request:

Delete
```
__dev/
```
route
Remove instrumentation (emitters, proxies)
Uninstall added deps if unused elsewhere
Search for
```
EXPLANATORY-PLAYGROUND
```
markers

Report what was removed.

当收到移除请求时：

删除
```
__dev/
```
路由
移除埋点代码（事件发射器、代理）
若相关依赖未在其他地方使用，卸载该依赖
搜索
```
EXPLANATORY-PLAYGROUND
```
标记，确保全部清理

向用户报告已移除的内容。