1---
2name: chart
3version: 3.0.2
4description: |
5  Interactive web charts: line, bar, candle, scatter, with HTML and screenshot output.
6 
7  Use when visualizing data for analysis or BI (e.g. plot BTC vs gold last year, bar chart of revenue by quarter, compare two return series).
8 
9metadata:
10  starchild:
11    emoji: "📊"
12    skillKey: chart
13 
14user-invocable: true
15disable-model-invocation: false
16 
17---
18 
19# Chart — Project-Based Interactive Charting
20 
21Generate interactive chart pages with Apache ECharts. Each chart lives in a dedicated project folder under `output/chart-html/`, making it easy to reuse and iterate.
22 
23## When to Use
24 
25Any time the user wants a visual chart: price charts, comparisons, dashboards, business analytics, etc.
26 
27## Architecture
28 
29- **ECharts** (CDN) for rendering
30- **ECharts native export (`getDataURL`) + canvas merge** for reliable PNG output
31- **Project-based storage**: one folder per chart project
32- **No gallery mode**: all artifacts stay in the project folder
33 
34## Project Structure (Required)
35 
36Each chart project should follow:
37 
38```
39output/chart-html/
40  <project-name>/
41    index.html        # chart page
42    generate.py       # generation script (for reproducibility)
43    README.md         # title / description / data source notes
44    data.json         # data snapshot
45    screenshot.png    # saved image
46```
47 
48Example folder name: `btc-90d-20260401`
49 
50## Workflow
51 
52### Step 1: Pick template or custom layout
53 
54Available templates:
55 
56| Template | Best for |
57|---|---|
58| `line.html` | Time-series trends, multi-series comparisons |
59| `bar.html` | Category comparisons, rankings |
60| `pie.html` | Composition / share breakdown |
61| `candlestick.html` | OHLCV price charts |
62| `scatter.html` | Correlation, distribution |
63| `dashboard.html` | KPI cards + 2×2 multi-chart grid |
64| `radar.html` | Multi-dimension scoring |
65| `heatmap.html` | Matrix / calendar intensity |
66| `dual-axis.html` | Two series with very different scales (e.g. market cap vs stablecoin supply) — left and right Y axes, each with its own label color |
67| `multi-panel.html` | Stacked panels sharing one X axis (e.g. price + volume + RSI) — single ECharts instance, tooltip/zoom synced across all panels |
68| `waterfall.html` | Incremental contribution breakdown (e.g. P&L attribution, budget variance) — positive/negative bars stacked on a floating base |
69 
70### Step 2: Create project folder
71 
72Use `create_project(name, description, data_sources)` from `scripts/build_chart.py`.
73 
74### Step 3: Build and save chart page
75 
76Use either:
77- `build_chart(template_name, ...)`
78- `build_chart_custom(...)`
79 
80Then save as `index.html` in the project folder:
81- `save_chart(html, project_dir=project_dir)`
82 
83### Step 4: Save reproducible assets
84 
85Also save:
86- `save_generate_script(script_content, project_dir)` → `generate.py`
87- `save_data(data, project_dir)` → `data.json`
88- project README is created by `create_project(...)`
89 
90### Step 5: Serve preview
91 
92Use project-root serving (recommended):
93 
94```python
95preview_serve(
96  title="Chart Preview",
97  dir="skills/chart/scripts",
98  command="python3 chart_server.py /data/workspace/output/chart-html 7860",
99  port=7860
100)
101```
102 
103Then open: `/preview/<id>/<project-name>/index.html`
104 
105Important behavior in v3.0.1:
106- `chart_server.py` now rewrites preview-prefixed static paths internally (`/preview/<id>/...` → `/...`) before filesystem lookup.
107- This guarantees the preview iframe resolves the real project `index.html` instead of falling back to root directory listing.
108- Keep project pages under `output/chart-html/<project>/index.html` (do not serve `output/chart-html` directly as a static preview without `chart_server.py`).
109 
110### Step 6: Export image
111 
112Two modes:
1131. **User wants web page + image**: click "💾 Save Image" in page toolbar, saves to current project as `screenshot.png`
1142. **User wants image only**: call `screenshot_chart(project_dir)` (Playwright) and send `screenshot.png` directly
115 
116## Toolbar Requirements
117 
118Every chart page must include these buttons:
119 
120```html
121<div class="actions">
122  <button onclick="downloadPNG(this)">📥 Download PNG</button>
123  <button onclick="copyToClipboard(this)">📋 Copy Image</button>
124  <button onclick="saveToProject(this)">💾 Save Image</button>
125</div>
126```
127 
128Do not include gallery entry.
129 
130## Key Files
131 
132| File | Purpose |
133|------|---------|
134| `skills/chart/scripts/base-styles.css` | Base dark theme CSS |
135| `skills/chart/scripts/base-export.js` | Export helpers: download/copy/save-to-project |
136| `skills/chart/scripts/build_chart.py` | Project creation, HTML build, data/script save, screenshot |
137| `skills/chart/scripts/chart_server.py` | Static server + `/save-chart` API |
138| `skills/chart/templates/*.html` | Reusable chart templates |
139| `output/chart-html/<project>/*` | All generated chart artifacts |
140 
141## Notes
142 
143- Embed data directly in HTML (`const DATA = ...`) to avoid iframe CORS issues.
144- For multi-chart pages, register all chart instances in `window.CHART_INSTANCES`.
145- Use meaningful project names (`topic-range-date`) for easy lookup.
146