Phase 1: Implement React Flow visualization canvas and adapter layer

[mjshuff23]

Parent: #1

Depends on: #4

Goal

Build the visualization layer that turns canonical data-structure states and trace highlights into visible nodes, edges, labels, controls, and replay states.

React Flow is the recommended first choice because this app needs custom nodes, custom edges, viewport controls, minimaps, layouting, drag/pan/zoom, save/restore patterns, and graph/tree visualization support. Use it as the canvas engine, but keep it behind an adapter so the data-structure engine does not depend on React Flow types.

Core architecture

Data flow should look like this:

OperationCommand
  -> data-structure engine
  -> OperationTrace
  -> current TraceStep
  -> VisualizationAdapter
  -> React Flow nodes/edges
  -> Canvas render

Do not let the canvas mutate the canonical structure state directly.

Required modules

• src/features/visualizer/types.ts
• src/features/visualizer/VisualizationCanvas.tsx
• src/features/visualizer/adapters/**
• src/features/visualizer/nodes/**
• src/features/visualizer/edges/**
• src/features/visualizer/layout/**
• src/features/visualizer/highlights/**

Adapter interface draft

interface VisualizationAdapter<TState> {
  structure: StructureKind;
  toFlowModel(input: {
    state: TState;
    highlights?: Highlight[];
    viewportMode?: 'compact' | 'detailed';
  }): {
    nodes: Node[];
    edges: Edge[];
  };
}

The actual implementation can refine the types, but the adapter boundary should remain explicit.

Initial adapters

• Stack adapter
• Queue adapter
• Generic linear collection adapter helper

Canvas features

• Render React Flow with nodes/edges from the adapter.
• Add controls for zoom/pan/fit view.
• Add minimap only when useful; hide on small screens if cramped.
• Add custom node components for values, pointer labels, and active states.
• Add semantic highlight classes for active/comparing/visited/inserted/removed/error.
• Add read-only mode for normal playback.
• Add optional inspect mode to click a node and view metadata.
• Add empty state when no structure is loaded.
• Add error state when adapter receives invalid state.

Layout requirements

• Linear structures should be stable and predictable; avoid physics/force layout for stacks/queues.
• Trees/heaps/graphs can use layout helpers later, but this issue should define a layout module boundary now.
• Node positions should not jitter between trace steps unless movement is part of the teaching moment.
• Prefer deterministic coordinates in tests.

Accessibility requirements

• Canvas must have an accessible label explaining what is visualized.
• Current operation step must be available outside the canvas as text.
• Critical information must not be color-only.
• Keyboard focus should not get trapped in the canvas.

Tests required

• Unit tests for adapter output shape from stack/queue states.
• Component test renders the canvas with known nodes/edges.
• Test highlight mapping for active/inserted/removed states.
• Test empty/error states.
• Playwright smoke test loads playground and sees canvas content.

Acceptance criteria

• Stack and queue states from Phase 0: Build core data-structure engine and OperationTrace schema #4 render visually.
• Visualization updates when the selected trace step changes.
• Algorithm state remains owned by the engine, not by React Flow.
• The adapter layer is documented enough for future structures.

Non-goals

• Do not implement operation controls here; use fixed/mock states if needed.
• Do not implement persistence here.
• Do not implement every structure adapter here.

Reference docs

• React Flow quick start: https://reactflow.dev/learn
• React Flow custom nodes: https://reactflow.dev/learn/customization/custom-nodes
• React Flow layouting: https://reactflow.dev/learn/layouting/layouting
• React Flow save/restore example: https://reactflow.dev/examples/interaction/save-and-restore
• React Flow testing: https://reactflow.dev/learn/advanced-use/testing
• React Flow accessibility: https://reactflow.dev/learn/advanced-use/accessibility