explanatory-playground

Explanatory Playground

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

Workflow

1. Clarify the target

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"

2. Identify what's hidden

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

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.

4. Choose interactivity level

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.

6. Instrument minimally

Prefer event emitters (least invasive):

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:

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

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

Guard against production:

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

8. Document removal

Header in every created file:

/**
 * 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:

1. Delete __dev/ route
2. Remove instrumentation (emitters, proxies)
3. Uninstall added deps if unused elsewhere
4. Search for EXPLANATORY-PLAYGROUND markers

Report what was removed.