feat(echarts): implement waveform-audio

[github-actions]

Implementation: waveform-audio - javascript/echarts

Implements the javascript/echarts version of waveform-audio.

File: plots/waveform-audio/implementations/javascript/echarts.js

Parent Issue: #4563

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white (#FAF8F1) background. The title "waveform-audio · javascript · echarts · anyplot.ai" appears centered at the top in dark ink, clearly readable. Y-axis is labeled "Amplitude" and X-axis "Time (s)", both in secondary ink (inkSoft). Tick labels at 14px are well-spaced and legible. A filled area waveform in Imprint brand green (#009E73) shows a speech-like signal from 0 to 1.0 s. The gradient fill (opaque at extremes, transparent near zero) creates a professional DAW-style appearance. Three distinct amplitude peaks (syllabic bursts) are visible with near-silence between them. A horizontal zero reference line runs across the full width. Subtle y-axis grid lines are present. All text is clearly readable against the light background.

Dark render (plot-dark.png): The same chart on a warm near-black (#1A1A17) background. Title, axis labels, and tick labels all shift to lighter ink tokens and remain fully readable — no dark-on-dark failures. The brand green waveform (#009E73) is identical to the light render; only the chrome has flipped. The semi-transparent gradient fill integrates cleanly with the dark background. The zero reference line is visible in the lighter inkSoft tone. Grid lines use the dark-theme grid token and are subtle. All text is clearly readable against the dark background.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 84/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	12	20
Spec Compliance	14	15
Data Quality	14	15
Code Quality	9	10
Library Mastery	7	10
Total	84	100

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set; minor: axis names at fontSize:18 slightly large relative to tick labels at 14 but not distracting
• VQ-02: No Overlap (6/6) — No overlapping elements in either render
• VQ-03: Element Visibility (5/6) — Dense waveform rendered well; gradient fill compensates for thin 1px line
• VQ-04: Color Accessibility (2/2) — Single series brand green, CVD-safe, adequate contrast on both surfaces
• VQ-05: Layout & Canvas (4/4) — Good proportions, waveform spans full width, balanced margins
• VQ-06: Axis Labels & Title (2/2) — "Time (s)" with units; "Amplitude" is standard for normalized audio
• VQ-07: Palette Compliance (2/2) — First series t.palette[0]=#009E73, theme-correct backgrounds and all chrome tokens wired

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Above defaults: gradient fill creates professional DAW aesthetics. Not publication-ready; syllabic peaks are the insight but nothing draws attention to them
• DE-02: Visual Refinement (4/6) — Good: y-axis-only grid, zero reference via markLine, no redundant legend, subtle token-driven chrome
• DE-03: Data Storytelling (3/6) — Deliberate speech-like data choice adds potential narrative, but no visual hierarchy or emphasis highlights the three peaks

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Correct filled area symmetric around zero via areaStyle origin:0
• SC-02: Required Features (3/4) — All key features present; minor omission: no min/max envelope rendering as recommended by spec for dense waveforms
• SC-03: Data Mapping (3/3) — X=time (0–1.0 s), Y=normalized amplitude (−1.0 to +1.0). Correct
• SC-04: Title & Legend (3/3) — Title format correct; no legend appropriate for single series

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows dynamics, near-silence, transients, harmonic content. Missing: no clipping demonstration (spec lists it as a key feature to reveal)
• DQ-02: Realistic Context (5/5) — Highly realistic: 175 Hz fundamental, 4 harmonics, 3 Gaussian syllabic envelopes — scientifically grounded
• DQ-03: Appropriate Scale (4/4) — 1 s duration, 5000 samples, amplitude −1 to +1 all correct

Code Quality (9/10)

• CQ-01: KISS Structure (2/3) — Small hexToRgba helper function deviates from flat no-functions rule; function is purposeful but still breaks the guideline
• CQ-02: Reproducibility (2/2) — Fully deterministic: pure trigonometric functions with fixed parameters
• CQ-03: Clean Imports (2/2) — No unused globals; all referenced symbols are harness-provided
• CQ-04: Code Elegance (2/2) — Clean, readable JS; no over-engineering or fake functionality
• CQ-05: Output & API (1/1) — Follows harness contract; outputs plot-{theme}.png + .html

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good: line series with areaStyle, markLine, gradient colorStops, token-driven config
• LM-02: Distinctive Features (3/5) — Uses ECharts-specific gradient area fill (areaStyle with colorStops and origin:0) and markLine reference; does not reach distinctively unique ECharts capability

Score Caps Applied

• None — DE-01=5 > 2, no "correct but boring" cap; all other caps bypassed

Strengths

• Correct waveform plot type: filled area symmetric around zero via ECharts areaStyle origin:0
• Imprint brand green (#009E73) correctly wired via t.palette[0]; all chrome tokens (ink, inkSoft, grid) properly applied
• Sophisticated gradient fill mimics professional DAW waveform aesthetics
• Excellent synthetic data: 175 Hz fundamental + 4 harmonics + 3 Gaussian syllabic envelopes — highly realistic speech-like signal
• Fully deterministic (pure math); zero reference line via markLine

Weaknesses

• No visual storytelling: the three syllabic peaks are the core insight but nothing highlights them — add subtle vertical annotations or shaded regions marking syllable centers (0.14s, 0.47s, 0.81s) to elevate DE-01 and DE-03
• Spec recommends min/max envelope rendering for dense waveforms to avoid aliasing — implement a downsampled min/max envelope (e.g. 200 bins) as a solid fill behind the fine line for authentic DAW-style rendering
• Gradient fill (vertical, fading from top/bottom) is not symmetric in perceived weight: the gradient makes the bottom half of the waveform nearly invisible at zero — consider a symmetric gradient that radiates outward from zero in both directions equally, or use two envelope series (positive/negative) for better visual balance
• hexToRgba helper function breaks the flat KISS structure — inline the rgba string or leverage ECharts' built-in color string support

Issues Found

1. DE-03 LOW: Data choice is good (speech-like syllabic bursts) but no visual hierarchy draws attention to the peaks — the chart shows rather than tells
   • Fix: Add 3 lightweight vertical markLines or shaded markArea spans at the syllable centers (t=0.14, 0.47, 0.81) with subtle labels — this creates a clear story and raises both DE-01 and DE-03
2. SC-02 MINOR: Dense waveform spec recommends min/max envelope rendering to prevent aliasing at lower zoom levels
   • Fix: Compute a 200-bin min/max envelope from the 5000 samples and render as a filled band series; the fine oscillation line can be kept as an overlay for texture
3. DE-01 GRADIENT: Gradient is not symmetric around zero — the fill fades from opaque at top edge to transparent at center; the bottom half mirrors this, but visually the waveform looks heavier at top/bottom edges rather than at the amplitude peaks
   • Fix: Use origin: 0 and style the gradient so opacity correlates with distance from zero (stronger alpha = larger amplitude), not with canvas position; alternatively, use two areaStyle series for the positive and negative envelopes

AI Feedback for Next Attempt

The implementation is technically solid with correct chart type, palette compliance, and realistic data. To reach ≥ 90: (1) Add syllable annotations via markLine or markArea at 0.14s, 0.47s, 0.81s — this transforms the chart from a data display into a story about speech rhythm, immediately boosting DE-03 and DE-01. (2) Rework the gradient fill to radiate outward from zero symmetrically (opacity proportional to |amplitude|, not canvas y-position) so the waveform's dynamic peaks visually stand out over the quiet regions. (3) Remove the hexToRgba helper — inline as a template literal or use ECharts' native color-object API. These three changes together should push the score above 90.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/4

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

Light render (plot-light.png): The plot displays on a warm off-white (#FAF8F1) background. The waveform is rendered in brand green (#009E73) with a gradient area fill — opaque near the top (62% alpha) fading to near-transparent (5%) at zero on the upper envelope, and mirrored for the lower envelope. Three labeled syllabic regions ("Syllable 1", "Syllable 2", "Syllable 3") are highlighted with faint semi-transparent green rectangles and subtle borders. A horizontal zero-reference line runs across the center. The Y-axis shows "Amplitude" with tick labels from -1.0 to 1.0; the X-axis shows "Time (s)" from 0 to 1.00. The title "waveform-audio · javascript · echarts · anyplot.ai" is centered at the top in dark ink. All text is fully readable against the light background — no legibility issues.

Dark render (plot-dark.png): The same plot on a warm near-black (#1A1A17) background. The waveform data colors are identical to the light render — brand green (#009E73) with the same gradient fill. Chrome flips correctly: the title, axis labels ("Amplitude", "Time (s)"), and tick labels all render in light text (#F0EFE8 / #B8B7B0). The syllable region labels ("Syllable 1/2/3") are rendered in t.inkSoft (light gray, ~#B8B7B0) and are legible against the dark-tinted mark-area fills. Grid lines are subtle. No dark-on-dark failures detected — all text is clearly readable against the dark background.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 92/100

Category	Score	Max
Visual Quality	29	30
Design Excellence	14	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	9	10
Total	92	100

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 22, axis names 18, tick labels 14, syllable labels 12). Proportions are well-balanced. Minor deduction: syllable region labels at fontSize 12 are slightly small on the canvas.
• VQ-02: No Overlap (6/6) — No overlapping text elements. Syllable labels sit cleanly inside their respective regions.
• VQ-03: Element Visibility (6/6) — Min/max envelope binning (300 bins over 5000 samples) is the correct approach for dense waveform data. The gradient fill makes the envelope shape immediately legible.
• VQ-04: Color Accessibility (2/2) — Single series in brand green with semi-transparent fill; good contrast on both surfaces. CVD-safe.
• VQ-05: Layout & Canvas (4/4) — Landscape orientation appropriate for a time-domain waveform. Good use of canvas area with balanced margins.
• VQ-06: Axis Labels & Title (2/2) — "Time (s)" and "Amplitude" are descriptive; normalized amplitude range is self-explanatory from the ±1 tick labels.
• VQ-07: Palette Compliance (2/2) — First (and only) series is #009E73 (t.palette[0]) ✓. Background is transparent (inherits #FAF8F1 / #1A1A17 from page) ✓. All chrome tokens (t.ink, t.inkSoft, t.grid) are applied and theme-correct in both renders ✓.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Clearly above a generic default: gradient area fill with origin: 0 (fills from the zero axis outward), mirrored inverted gradient on the lower envelope, and semi-transparent syllabic region shading create a polished, DAW-like aesthetic. Not quite publication-ready (missing typography finesse), but a strong design.
• DE-02: Visual Refinement (4/6) — Y-axis-only grid lines with t.grid color; no top/right spines (ECharts default L-frame); generous whitespace around the plot; containLabel: true prevents any label overflow. Solid refinement.
• DE-03: Data Storytelling (4/6) — The labeled syllabic regions create a clear narrative about speech structure — the viewer immediately understands that this is a 3-syllable utterance with distinct intensity envelopes. Zero reference line and gradient peak emphasis reinforce the story. Good visual hierarchy.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct waveform plot with filled area mirrored around zero. Min/max envelope rendering explicitly implemented per spec requirement for dense waveforms.
• SC-02: Required Features (4/4) — Filled area (above and below zero) ✓; semi-transparent fill ✓; horizontal zero-line reference ✓; X-axis time in seconds ✓; Y-axis normalized amplitude −1 to +1 ✓; min/max envelope to avoid aliasing ✓; synthetic audio data ✓.
• SC-03: Data Mapping (3/3) — Time on X, amplitude on Y; full ±1 range displayed; all 5000 samples (via 300-bin envelope) represented.
• SC-04: Title & Legend (3/3) — Title is exactly "waveform-audio · javascript · echarts · anyplot.ai" ✓. No legend appropriate for single-series.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Three distinct syllabic bursts with Gaussian envelopes, inter-syllable near-silence, varying peak amplitudes (env1 at 0.85, env2 at 0.748, env3 at 0.612), and a 175 Hz fundamental with 4 harmonics fully showcase waveform dynamics, clipping headroom, and the envelope-vs-carrier relationship.
• DQ-02: Realistic Context (5/5) — Gaussian syllabic amplitude envelopes over a voiced carrier (175 Hz with harmonics) is exactly how real speech waveforms appear. The 1-second, 3-syllable scenario is immediately recognizable to any audio engineer.
• DQ-03: Appropriate Scale (4/4) — 5000 samples over 1 second, 175 Hz fundamental with realistic harmonic decay weights (0.48 / 0.26 / 0.14 / 0.09 / 0.03), normalized amplitude ±1: all values are physically correct and domain-appropriate.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clear linear flow: tokens → data generation → downsampling → init → setOption. No functions or classes.
• CQ-02: Reproducibility (2/2) — Fully deterministic: pure mathematical formula, no random number generation.
• CQ-03: Clean Imports (2/2) — No imports; only window.ANYPLOT_TOKENS and window.echarts globals used.
• CQ-04: Code Elegance (2/2) — Appropriately complex for the task. The min/max binning loop is clean and necessary. Gradient color stops are verbose but correct.
• CQ-05: Output & API (1/1) — ECharts is an interactive library; harness generates both .png and .html. animation: false set correctly.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Uses areaStyle.origin: 0 (fill from zero line rather than axis bottom), markLine with silent: true for the zero reference, markArea with region labels, gradient colorStops on areaStyle.color, and symbol: "none" to suppress point markers — all idiomatic ECharts patterns.
• LM-02: Distinctive Features (4/5) — markArea for time-region annotation with labels is an ECharts-specific feature; gradient areaStyle with origin: 0 is distinctive; the mirrored dual-series envelope approach exploits ECharts area fill behavior in a way specific to the library. Minor deduction: no tooltip or dataZoom configuration even as non-rendering setup.

Score Caps Applied

• None — No caps apply. DE-01=6 and DE-02=4, both above the cap threshold.

Strengths

• Min/max envelope binning (300 bins from 5000 samples) correctly avoids aliasing — spec explicitly required this for dense waveforms
• Gradient areaStyle with origin: 0 creates an authentic DAW-like filled waveform appearance
• Syllabic region annotations (markArea) add genuine storytelling value beyond just displaying raw signal
• Fully deterministic data generation using a physically plausible speech model (Gaussian envelopes + harmonic carrier)
• Perfect theme adaptation: both renders pass legibility checks with no dark-on-dark failures

Weaknesses

• Syllable region labels are at fontSize 12, which is slightly small on the 3200×1800 canvas — consider increasing to 14–15 for better mobile readability
• Axis name labels at fontSize 18 are somewhat large relative to tick labels at 14; a nameTextStyle fontSize of 15–16 would be more proportionally balanced

Issues Found

1. VQ-01 MINOR: Syllable labels at fontSize: 12 are slightly small on the full-resolution canvas
   • Fix: Increase markArea.label.fontSize from 12 to 14–15
2. DE-01 MINOR: Typography hierarchy could be tightened (axis name 18 vs tick 14 gap is wide)
   • Fix: Reduce nameTextStyle.fontSize from 18 to 15–16 on both axes

AI Feedback for Next Attempt

The core implementation is excellent — min/max envelope, gradient fill, syllabic regions, and perfect theme adaptation are all strong. The minor refinements for a further attempt would be: (1) increase syllable label font size from 12 to 14–15, (2) reduce axis name fontSize from 18 to 15–16 for better typographic balance with the 14pt tick labels.

Verdict: APPROVED