| # 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 |
| |
