visualization Specification
Purpose
Present the 7-layer progressive translation as an interactive, toy-like experience: a custom WebGL 3D card stack and a 2D parallel-sets view, served by FastAPI (not Gradio, for the "Off-Brand" bonus), with per-layer audio playback.
Ownership note: the frontend implementation under
static/*is owned by a separate coding agent and MUST NOT be edited by others. This spec captures the intended behavior, not implementation details to change here.
Requirements
Requirement: Custom FastAPI-served frontend
The visualization SHALL be a fully custom HTML/CSS/JS frontend served directly by FastAPI (no default Gradio UI), to satisfy the "Off-Brand" bonus.
Scenario: Frontend served from root
- WHEN a user opens the app root URL
- THEN the custom frontend is served and static assets are available under
/static
Requirement: 3D card stack and 2D parallel-sets views
The frontend SHALL provide a WebGL (Three.js, vendored locally) 3D card-stack view and a 2D parallel-sets view of the same seven layers.
Scenario: Both views available
- WHEN a translation result is rendered
- THEN the user can view it as a 3D card stack (original at back, final at front) and as a 2D parallel-sets diagram
Requirement: Source-to-target gradient colorization
Phrase blocks SHALL be colorized along a purple (source) to cyan (target) gradient, and adjacent-layer phrase blocks SHALL be connected by broad elevated translucent ribbons.
Scenario: Gradient and ribbons
- WHEN layers and links are rendered
- THEN blocks are colored from purple (source) to cyan (target) and adjacent layers are joined by translucent ribbons, with reordering shown as crossings
Requirement: Interactive tracing and playback
The frontend SHALL let the user hover to trace a single phrase across all layers, play per-layer audio, play all layers in sequence, and request a random example via a "Surprise me" button.
Scenario: Hover trace
- WHEN the user hovers over a phrase block
- THEN that phrase's path is highlighted across every layer
Scenario: Audio playback
- WHEN the user triggers playback on a layer or "play all"
- THEN the corresponding layer audio is played (one layer, or all in sequence)
Scenario: Surprise me
- WHEN the user clicks "Surprise me"
- THEN a random curated example is loaded and translated