plotters-skill 0.1.0

package/README.md

@@ -0,0 +1,212 @@
+# PlottersSkill
+
+<p align="center">
+  <img src="assets/demo_01.gif" alt="PlottersSkill Demo" width="100%">
+</p>
+
+<p align="center">
+  <img src="assets/banner_1.png" alt="PlottersSkill Banner" width="50%">
+</p>
+
+High-performance plotting for TypeScript / JavaScript, powered by the Rust
+[plotters](https://github.com/plotters-rs/plotters) crate with a
+**matplotlib pyplot-like API**.
+
+Works in **Node.js** (native addon via napi-rs) and the **browser**
+(WASM + SVG / Canvas via wasm-bindgen).
+
+## Quick Start
+
+### Node.js
+
+```bash
+npm install plotters-skill
+```
+
+```typescript
+import { figure } from 'plotters-skill';
+
+const fig = figure();
+fig.title('Hello PlottersSkill');
+fig.plot([0, 1, 2, 3, 4], [10, 25, 18, 30, 22], {
+  color: 'steelblue', label: 'Revenue',
+});
+fig.savefig('chart.png');
+```
+
+### Browser (WASM)
+
+```typescript
+import init, { figure } from 'plotters-skill';
+
+await init();
+const fig = figure();
+fig.hist([1, 2, 2, 3, 3, 3, 4, 5], { bins: 10, color: 'steelblue' });
+fig.draw(canvas);  // render to an HTML5 Canvas element
+```
+
+## Chart Types
+
+| Chart | `figure()` | `axes()` | Node | WASM |
+|-------|:----------:|:--------:|:----:|:----:|
+| Histogram | ✅ | — | ✅ | ✅ |
+| Pie / Donut | ✅ | — | ✅ | ✅ |
+| Box Plot | ✅ | — | ✅ | ✅ |
+| Area (fillBetween) | ✅ | ✅ | ✅ | ✅ |
+| Candlestick (OHLC) | ✅ | — | ✅ | ✅ |
+| Line | ✅ | ✅ | ✅ | ✅ |
+| Scatter | — | ✅ | ✅ | ✅ |
+| Bar | — | ✅ | ✅ | ✅ |
+| Step | — | ✅ | ✅ | ✅ |
+
+## API Overview
+
+| Function | pyplot Equivalent | Description |
+|----------|-------------------|-------------|
+| `figure()` | `plt.figure()` | Single figure — hist, pie, plot, fillBetween, candlestick, boxplot |
+| `axes()` | `fig, ax = plt.subplots()` | Flexible Cartesian axes — mix plot, scatter, bar, step, fillBetween |
+| `subplots(nrows, ncols)` | `plt.subplots(nrows, ncols)` | Uniform NxM subplot grid |
+| `gridFigure()` | `plt.subplot_mosaic()` | Flexible grid — each row can have different column counts |
+
+## Examples
+
+### Multi-series overlay (auto-cycling colours)
+
+```typescript
+import { figure } from 'plotters-skill';
+
+const fig = figure();
+fig.title('Sales Comparison');
+fig.xlabel('Month');
+fig.ylabel('Revenue');
+fig.fillBetween(months, seriesA, { alpha: 0.3, label: 'Product A' });
+fig.fillBetween(months, seriesB, { alpha: 0.3, label: 'Product B' });
+fig.savefig('comparison.png');
+```
+
+### Mixed series with axes()
+
+```typescript
+import { axes } from 'plotters-skill';
+
+const ax = axes();
+ax.figsize(900, 540);
+ax.title('Trend vs Actual');
+ax.xlabel('x');
+ax.ylabel('y');
+ax.plot([0, 1, 2, 3, 4], [10, 25, 18, 30, 22], {
+  color: 'steelblue', lineWidth: 2, label: 'Trend',
+});
+ax.scatter([0, 1, 2, 3, 4], [12, 20, 22, 28, 25], {
+  color: 'coral', markerSize: 6, label: 'Actual',
+});
+ax.legend(true);
+ax.savefig('chart.png');
+```
+
+### Subplot grid
+
+```typescript
+import { subplots } from 'plotters-skill';
+
+const grid = subplots(1, 2);
+grid.figsize(1200, 500);
+grid.suptitle('Dashboard');
+
+let ax = grid.ax(0, 0);
+ax.hist(data, { bins: 25, color: 'steelblue' });
+grid.setAx(0, 0, ax);
+
+ax = grid.ax(0, 1);
+ax.pie([40, 30, 20, 10], {
+  labels: ['Web', 'Mobile', 'Desktop', 'Other'],
+});
+grid.setAx(0, 1, ax);
+
+grid.savefig('dashboard.png');
+```
+
+### Animated GIF (Node.js)
+
+```typescript
+const frames = [];
+for (let i = 2; i <= x.length; i++) {
+  frames.push([{ x: x.slice(0, i), y: y.slice(0, i) }]);
+}
+fig.savegif('animation.gif', { frames, delayMs: 200 });
+```
+
+## Output Formats
+
+| Format | Node | WASM |
+|--------|:----:|:----:|
+| PNG file (`savefig`) | ✅ | — |
+| Animated GIF (`savegif`) | ✅ | — |
+| SVG string (`render`) | ✅ | ✅ |
+| HTML5 Canvas (`draw`) | — | ✅ |
+
+## Colours
+
+Supports **matplotlib tab10** palette (`c0`–`c9`), common **CSS** names
+(`steelblue`, `coral`, `gold`, `teal`, …), and **hex** codes (`#RRGGBB`).
+Colours auto-cycle through tab10 when omitted in multi-series charts.
+
+## VS Code Extension
+
+The **PlottersSkill** extension brings chart generation directly into VS Code
+via Copilot Chat. Install the `.vsix` or search for "PlottersSkill" in the
+marketplace.
+
+### `@plotters` Chat Participant
+
+Type `@plotters` in Copilot Chat followed by a natural language description:
+
+```
+@plotters a histogram of 500 normally-distributed values with 30 bins
+@plotters /pie revenue split: Web 40%, Mobile 30%, Desktop 20%, Other 10%
+@plotters /line monthly sales for 2024 with three product lines
+```
+
+Slash commands: `/histogram`, `/pie`, `/line`, `/scatter`, `/area`, `/boxplot`,
+`/candlestick`, `/axes`, `/subplots`.
+
+### How it works
+
+1. Your prompt is sent to the Copilot LLM with the plotters-skill API reference
+2. The LLM generates a TypeScript script
+3. The script is **type-checked** against the `.d.ts` — errors are fed back for auto-fix (up to 3 retries)
+4. The passing script runs in a **sandboxed VM** — no filesystem or network access
+5. The rendered chart image is sent back to the LLM for **verification**
+6. The PNG is displayed inline in chat
+
+### Features
+
+| Feature | Description |
+|---------|-------------|
+| **Chart History** | Gallery sidebar in Explorer — browse, re-render, or delete past charts |
+| **Edit Script** | One-click button opens the generated TypeScript with a "▶ Render Chart" CodeLens |
+| **LLM Verification** | Charts are verified against the original request; mismatches trigger automatic retry |
+| **Inline Errors** | Type-check and runtime errors shown in chat during retries |
+| **Feedback Tracking** | 👍/👎 on chat responses tracked for stats (`PlottersSkill: Show Feedback Stats`) |
+| **Notebook Support** | `*.plotters-notebook` files — TypeScript cells execute with inline PNG output |
+| **Render from Editor** | `PlottersSkill: Render Chart from Active Editor` — run any `.ts` script directly |
+| **Configurable** | Settings for retry count, VM timeout, preferred model, and source visibility |
+
+### AI Skill Installation
+
+The bundled `SKILL.md` can be installed into any project so Copilot, Claude, or
+other AI tools automatically discover the plotters-skill API:
+
+```bash
+npx plotters-skill install-skill                    # all tools
+npx plotters-skill install-skill --target copilot   # .github/skills/plotters-skill/
+npx plotters-skill install-skill --target claude     # .claude/skills/plotters-skill/
+```
+
+## Development
+
+See [DEV.md](DEV.md) for prerequisites, build commands, tests, and project structure.
+
+## License
+
+MIT