explanatory-playground

name

explanatory-playground

description

Build interactive debugging interfaces that reveal internal system behavior. Use when asked to "help me understand how this works", "show me what's happening", "visualize the state", "build a debug view", "I can't see what's going on", or any request to make opaque system behavior visible. Applies to state machines, data flow, event systems, algorithms, render cycles, animations, CSS calculations, or any mechanism with hidden internals.

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.