docs/map/frontend.md

Frontend Map — frontend/

React 19 + TypeScript + Vite UI for ReplicaLab.

Tasks implemented: FND 01-10

Stack

Technology	Version	Purpose
React	19.2.0	UI framework
React Router	7.13.1	Client-side routing
Three.js	0.183.2	3D molecule scene
@react-three/fiber	9.5.0	React Three.js bindings
@react-three/drei	10.7.7	Three.js helpers
Framer Motion	12.35.1	Animations
@xyflow/react	12.10.1	Flow diagrams
Recharts	3.8.0	Charts and graphs
Tailwind CSS	4.2.1	Utility-first styling
Lucide React	0.577.0	Icons

Routes — App.tsx

Path	Component	Purpose
/	DashboardPage	Training overview, scenario selection
/episode	EpisodePage	Live episode viewer (new episode)
/episode/:episodeId	EpisodePage	Replay of completed episode

Pages

DashboardPage.tsx

• Scenario selection (family + difficulty)
• Training metrics display
• Episode history list
• Start new episode button

EpisodePage.tsx

• Live negotiation between Scientist and Lab Manager
• Protocol display and evolution
• Score breakdown when episode completes
• Replay controls for completed episodes

Components (15 files)

Negotiation & Protocol

Component	Purpose
NegotiationLog.tsx	Scrollable conversation between agents
ProtocolPanel.tsx	Current protocol details display
PaperPanel.tsx	Paper summary (title, hypothesis, method, finding)
LabInventory.tsx	Equipment and reagent availability
Controls.tsx	User controls (start, step, auto-play)

Visualization

Component	Purpose
ScorePanel.tsx	Rigor/feasibility/fidelity score bars
JudgeAuditPanel.tsx	Judge reasoning and audit trail
TrainingResults.tsx	Training metrics charts
ReplayViewer.tsx	Step-through replay of completed episodes

3D & Animation

Component	Purpose
CharacterStage.tsx	3D stage for agent characters
CharacterAvatar.tsx	Individual agent avatar
AnimatedCharacter.tsx	Character with animations
MoleculeScene.tsx	3D molecule visualization
TiltCard.tsx	Tilt-on-hover card component

Layout

Component	Purpose
Header.tsx	Top navigation bar

API Client — lib/api.ts

REST Functions

Function	Method	Endpoint
healthCheck()	GET	/health
getScenarios()	GET	/scenarios
resetEpisode(params)	POST	/reset
stepEpisode(action)	POST	/step
getReplay(episodeId)	GET	/replay/{episodeId}

WebSocket

Function	Purpose
createWebSocket(onMessage, onOpen, onClose, onError)	Connect to /ws
sendWsMessage(ws, msg)	Send typed message

Mock Data (for offline development)

Function	Returns
createMockConversation()	NegotiationMessage[]
createMockScores()	ScoreBreakdown
createMockEpisodeState(done)	EpisodeState
createMockProtocol()	Protocol
createMockJudgeAudit()	JudgeAudit

TypeScript Types — types/index.ts

Mirrors Python models:

TS Interface	Python Model
ScientistAction	ScientistAction
LabManagerAction	LabManagerAction
Protocol	Protocol
EpisodeState	EpisodeState
StepResult	StepResult
ScoreBreakdown	RewardBreakdown
FeasibilityReport	FeasibilityCheckResult (partial)
JudgeAudit	StepInfo.judge_notes + verdict
NegotiationMessage	ConversationEntry

Additional frontend-only types:

• TrainingMetrics — loss, reward curves
• TrainingComparison — baseline vs trained model
• PaperSummary — paper details for display
• LabConstraints — lab resource summary
• SuggestedChange — protocol revision display

Utility Files

lib/utils.ts

Shared helpers (class merging, formatting, etc.)

lib/audio.ts

Audio feedback utilities for UI interactions.

Assets

frontend/public/characters/
    judge.png           (~1.2 MB)
    lab-manager.png     (~900 KB)
    scientist.png       (~900 KB)