transparent-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Transparent UI

Build temporary debugging interfaces that make invisible system behavior visible. These are development-only routes/pages that reveal internal state, transitions, and data flow through interactive visualization.

构建临时调试界面，让原本不可见的系统行为可视化。这些仅用于开发环境的路由/页面，通过交互式可视化展示系统的内部状态、转换过程和数据流。

Core Principles

核心原则

Make the invisible visible. Show state that normally exists only in memory. Reveal transitions that happen too fast to observe. Surface the "why" behind system behavior.

Temporary by design. These are debugging tools, not production features. Keep changes isolated for easy removal. Use dev-only routes and environment checks.

Use existing components. Build with the project's component library and design system. The visualization should feel native to the codebase, not like a foreign debugging tool.

Match instrumentation to context. Sometimes minimal logging is enough; sometimes a full observable wrapper is needed. Choose the lightest approach that captures the necessary information.

让不可见的内容可视化。展示通常仅存在于内存中的状态，揭示发生速度过快而难以观察的转换过程，呈现系统行为背后的“原因”。

设计为临时工具。这些是调试工具，而非生产环境功能。保持修改的独立性以便于移除，使用仅开发环境可用的路由和环境检查机制。

使用现有组件。利用项目的组件库和设计系统进行构建，让可视化界面与代码库原生融合，而非像外来的调试工具。

根据场景选择埋点方式。有时仅需简单的日志记录即可，有时则需要完整的可观察包装器。选择最轻量的方案来捕获所需信息。

Workflow

工作流程

Step 1: Identify What to Make Transparent

步骤1：确定需要透明化的内容

Analyze the system and identify:

State: What values change over time? What's the shape of the data?
Transitions: What events trigger state changes? What's the sequence?
Relationships: How do components/modules communicate? What depends on what?
Hidden logic: What conditions, thresholds, or rules govern behavior?

Ask the user clarifying questions if the system boundary is unclear.

分析系统并确定：

状态：哪些值会随时间变化？数据的结构是什么？
转换过程：哪些事件会触发状态变化？触发顺序是怎样的？
关联关系：组件/模块之间如何通信？依赖关系是怎样的？
隐藏逻辑：哪些条件、阈值或规则主导了系统行为？

如果系统边界不清晰，向用户提出澄清问题。

Step 2: Choose Visualization Approach

步骤2：选择可视化方案

Select based on the system's nature. See references/patterns.md for domain-specific guidance.

System Type	Primary Visualization	Key Elements
State machines	Node-edge graph	States as nodes, transitions as edges, current state highlighted
Data flow	Directed graph or Sankey	Sources, transformations, sinks with data flowing between
Event systems	Timeline or sequence diagram	Events on time axis, handlers, propagation paths
Algorithms	Step-by-step animation	Data structure state at each step, highlighting active elements
Render/update cycles	Tree with diff overlay	Component tree, what re-rendered, why
Animations	Timeline scrubber	Keyframes, easing curves, current progress
CSS/Layout	Box model overlay	Computed values, constraint sources

根据系统类型选择合适的方案。如需领域特定的指导，请查看references/patterns.md。

系统类型	主要可视化方式	核心元素
状态机	节点-边图	状态为节点，转换为边，高亮当前状态
数据流	有向图或桑基图	数据源、转换过程、数据汇点，以及它们之间的数据流
事件系统	时间线或序列图	时间轴上的事件、处理程序、传播路径
算法	分步动画	每一步的数据结构状态，高亮活跃元素
渲染/更新循环	带差异覆盖的树状图	组件树、重新渲染的部分及原因
动画	时间线 scrubber	关键帧、缓动曲线、当前进度
CSS/布局	盒模型覆盖层	计算后的值、约束来源

Step 3: Design Interactivity Level

步骤3：设计交互级别

Layer interactivity based on debugging needs:

Level 1 - Observation: Real-time display of current state and recent changes. Always include this.

Level 2 - Inspection: Click/hover to see details. Expand nodes, view full payloads, trace data origins.

Level 3 - Manipulation: Trigger events, modify state, inject test data. Useful for reproducing edge cases.

Level 4 - Time travel: Record history, scrub through past states, replay sequences. Essential for race conditions and timing bugs.

Start with Level 1-2. Add 3-4 when the user needs them.

根据调试需求分层设计交互功能：

级别1 - 观察：实时显示当前状态和近期变化。这是基础必备功能。

级别2 - 检查：点击/悬停查看详情。展开节点、查看完整负载、追踪数据来源。

级别3 - 操作：触发事件、修改状态、注入测试数据。适用于复现边缘场景。

级别4 - 时间回溯：记录历史状态、回溯过往状态、重放序列。对于竞争条件和时序问题至关重要。

从级别1-2开始构建，当用户需要时再添加级别3-4的功能。

Step 4: Instrument the System

步骤4：系统埋点

Choose instrumentation strategy based on invasiveness tolerance:

Minimal (prefer when possible):

Add event emitters at key points
Wrap state setters to broadcast changes
Use existing debug/logging hooks if available

Wrapper/Proxy approach:

Create observable wrappers around the system
Intercept calls without modifying core code
Useful for third-party code or when core modifications are undesirable

Implementation patterns:

typescript

// Event emitter pattern - add to existing code
const debugEmitter = new EventEmitter();
function transition(from: State, to: State, event: string) {
  debugEmitter.emit('transition', { from, to, event, timestamp: Date.now() });
  // ... existing logic
}

// Proxy pattern - wrap without modifying
function createObservableStore<T>(store: T): T & { subscribe: (fn: Listener) => void } {
  const listeners: Listener[] = [];
  return new Proxy(store, {
    set(target, prop, value) {
      const oldValue = target[prop];
      target[prop] = value;
      listeners.forEach(fn => fn({ prop, oldValue, newValue: value }));
      return true;
    }
  });
}

根据对侵入性的容忍度选择埋点策略：

最小侵入式（优先选择）：

在关键位置添加事件发射器
包装状态设置器以广播变化
如果已有调试/日志钩子，直接使用

包装器/代理方案：

为系统创建可观察的包装器
在不修改核心代码的情况下拦截调用
适用于第三方代码或不希望修改核心代码的场景

实现模式：

typescript

// Event emitter pattern - add to existing code
const debugEmitter = new EventEmitter();
function transition(from: State, to: State, event: string) {
  debugEmitter.emit('transition', { from, to, event, timestamp: Date.now() });
  // ... existing logic
}

// Proxy pattern - wrap without modifying
function createObservableStore<T>(store: T): T & { subscribe: (fn: Listener) => void } {
  const listeners: Listener[] = [];
  return new Proxy(store, {
    set(target, prop, value) {
      const oldValue = target[prop];
      target[prop] = value;
      listeners.forEach(fn => fn({ prop, oldValue, newValue: value }));
      return true;
    }
  });
}

Step 5: Build the Debug Route

步骤5：构建调试路由

Create a development-only route that:

Guards against production: Check
```
process.env.NODE_ENV === 'development'
```
Connects to instrumentation: Subscribe to events/state changes
Renders visualization: Use the project's components where possible
Provides controls: Play/pause, speed, filters, time scrubbing as needed

Route structure (Next.js example):

app/
  __dev/
    transparent/
      [system]/
        page.tsx    # Dynamic route for different systems

Or simpler:

app/
  __dev/
    state-machine/
      page.tsx

Recommended libraries (install only if not already in project):

react-flow or reactflow: Node-edge graphs for state machines, data flow
framer-motion: Smooth transitions in visualization itself
Existing charting library: If project already has one, use it

创建仅用于开发环境的路由，需满足：

防止进入生产环境：检查
```
process.env.NODE_ENV === 'development'
```
连接埋点机制：订阅事件/状态变化
渲染可视化界面：尽可能使用项目现有组件
提供控制功能：按需添加播放/暂停、速度调节、过滤、时间回溯等控件

路由结构（Next.js示例）：

app/
  __dev/
    transparent/
      [system]/
        page.tsx    # 用于不同系统的动态路由

或更简单的结构：

app/
  __dev/
    state-machine/
      page.tsx

推荐库（仅在项目未包含时安装）：

react-flow 或 reactflow：用于状态机、数据流的节点-边图
framer-motion：实现可视化界面中的平滑过渡
现有图表库：如果项目已有图表库，优先使用

Step 6: Document Removal Path

步骤6：记录移除路径

At the top of every file created, add:

typescript

/**
 * TRANSPARENT-UI DEBUG TOOL
 *
 * Temporary debugging visualization. Remove when no longer needed:
 * 1. Delete this file: app/__dev/[name]/page.tsx
 * 2. Delete instrumentation: src/lib/[system]-debug.ts
 * 3. Remove debug hooks from: src/lib/[system].ts (lines XX-YY)
 *
 * Created for: [description of what this helps debug]
 */

在每个创建的文件顶部添加如下注释：

typescript

/**
 * TRANSPARENT-UI DEBUG TOOL
 *
 * Temporary debugging visualization. Remove when no longer needed:
 * 1. Delete this file: app/__dev/[name]/page.tsx
 * 2. Delete instrumentation: src/lib/[system]-debug.ts
 * 3. Remove debug hooks from: src/lib/[system].ts (lines XX-YY)
 *
 * Created for: [description of what this helps debug]
 */

Cleanup

清理

When the user asks to remove the transparent UI or is done debugging:

Delete debug route: Remove the
```
__dev/
```
page(s)
Remove instrumentation: Delete event emitters, proxies, debug hooks
Uninstall unused deps: If visualization libraries were added solely for this
Verify no remnants: Search for
```
debugEmitter
```
,
```
TRANSPARENT-UI
```
, or similar markers

Provide a summary of removed files and modified lines.

当用户要求移除Transparent UI或调试完成后：

删除调试路由：移除
```
__dev/
```
下的页面文件
移除埋点代码：删除事件发射器、代理、调试钩子
卸载未使用的依赖：如果仅为此工具安装了可视化库，将其卸载
检查残留：搜索
```
debugEmitter
```
、
```
TRANSPARENT-UI
```
或类似标记

向用户提供已删除文件和修改代码行的摘要。

Domain-Specific Patterns

领域特定模式

For detailed visualization patterns, layouts, and code examples organized by system type, see references/patterns.md.

如需按系统类型分类的详细可视化模式、布局和代码示例，请查看references/patterns.md。