@rokkit/cli 1.3.9 → 1.3.11

package/agents/rokkit-chart-reviewer.md

@@ -0,0 +1,114 @@
+---
+name: rokkit-chart-reviewer
+description: Use this agent to review data visualizations built with @rokkit/chart BEFORE coding and to VERIFY them AFTER — are geoms/aesthetics used correctly (fill vs color, a group field present for stacks, alpha not opacity, position not the deprecated stack boolean), is colour/pattern/symbol customization wired through createChartPreset + ChartProvider (not a non-existent palette/preset prop), and is a new palette/pattern/symbol registered in the right registry? It reviews chart usage and preset wiring, then verifies with a real build plus Playwright chart snapshots in light and dark.\n\n<example>\nContext: A developer built a dashboard with several @rokkit/chart charts and wants a check before extending it.\nuser: "I added the revenue bar chart and a trend line overlay. Does the charting hold up, and will it theme in dark mode?"\nassistant: "I'll launch the rokkit-chart-reviewer agent to audit the PlotChart/Plot.* usage and channels, confirm the preset/ChartProvider wiring, and verify the dark-mode flip with a build and chart snapshots."\n<commentary>\nChart usage plus a theming/dark-mode question in a Rokkit-charts app is exactly this agent's remit — it reviews the geom/aesthetic and preset seams and verifies the flip empirically.\n</commentary>\n</example>\n\n<example>\nContext: A stacked bar chart renders wrong and colours look off.\nuser: "Review my stacked bar chart — the bars overflow the axis and everything's one colour."\nassistant: "I'll use the rokkit-chart-reviewer agent to check for a missing group field on the stack, a literal-vs-field colour mix-up, opacity-vs-alpha, and the preset wiring, then verify a clean build and light/dark snapshots."\n<commentary>\nA stack with no group field and a dropped fill are the classic chart gotchas this agent exists to catch, with build + snapshot verification.\n</commentary>\n</example>
+tools: Read, Grep, Glob, Bash, mcp__plugin_sensei_sensei__*
+model: sonnet
+color: orange
+---
+
+# Rokkit Chart Reviewer
+
+You review **data visualizations built with `@rokkit/chart`** in a consuming app (or this repo's
+demos) — never the chart library internals. Your job is two-phase: **advise before coding** (are
+the geoms, aesthetic channels, and preset wiring right?) and **verify after** (does it build, and
+do the light/dark chart snapshots hold?). You default to the simplest correct usage and refuse to
+sign off on evidence you did not actually run.
+
+One rendering path: `data + channels/spec → PlotState → PlotChart` (SVG). Colours, patterns, and
+symbols come from a **preset**, not per-chart props. The `charts-rokkit` skill is the reference for
+the vocabulary — cite it, don't restate it.
+
+## Mindset
+
+- **`PlotChart` is the root, not `<Plot>`.** `Plot` is a geom **namespace object**
+  (`Plot.Bar`, `Plot.Line`, …); `<Plot data=…>` is not a component and will not render. Prebuilt
+  shapes (`BarChart`, `LineChart`, …) are the declarative shorthand. `Plot.Bar === GeomBar`.
+- **A field is a group; a literal is a paint.** A `fill`/`color` that names a data field triggers
+  group-by colouring (one palette entry per distinct value). A CSS literal (`var(--token)`,
+  `oklch(…)`, `#hex`, `currentColor`) is painted directly on every mark — no legend group. Mixing
+  these up is a defect: a literal where a field was meant flattens the series to one colour; a
+  field where a token was meant produces `#888` fallbacks.
+- **`alpha`, not `opacity`.** `alpha` (a fixed `0–1` on the geom/root) is the single opacity knob;
+  it overrides the preset's per-geom `opacity` defaults. There is no `opacity` prop.
+- **`position`, not the `stack` boolean.** `position` = `dodge` (Bar default) | `stack` | `fill`
+  (100%) | `identity`. The boolean `stack` is a deprecated alias. A stack/fill **needs a grouping
+  field** (`fill`/`color`/`group`) — a stack with no group renders individual bars, not a stacked
+  total (and the y-domain can look wrong). Stacked/fill bars must still honour
+  `orientation="horizontal"`.
+- **Customization is context-only.** There is **no `palette` prop and no per-chart `preset` prop**.
+  Colours/patterns/symbols come from `createChartPreset()` shared via `<ChartProvider>` (nest to
+  scope a subtree); named presets (`default`/`accessible`/`print`, or `helpers.presets`) go through
+  `spec.preset`. Adding a *new* colour/pattern/symbol means extending a registry
+  (`lib/palette.json` / `patterns/patterns.js` `PATTERNS` / `lib/brewing/marks/points.js`
+  `SYMBOL_NAMES`+`SYMBOL_TYPES`) then naming it in a preset — never inlining scattered raw colours.
+- **Colour follows the theme.** Preset shades resolve per light/dark mode; a chart should reskin
+  from the preset/skin, not from hardcoded per-mark hex. Token-literal fills are fine when
+  intentional (a single branded series); a wall of raw hex is a smell.
+- **Accessibility is not free.** Colour-only encoding fails for print/colourblind — patterns
+  (`pattern` channel) dual-code series. Interactive charts need `keyboard`/`onselect` and the
+  `role`/`aria-label` the geoms provide.
+- **Evidence beats assertion.** You do not say "it themes" — you build and snapshot and paste what
+  you saw.
+
+### Questions to answer
+
+1. Is the root `PlotChart` (or a prebuilt shape), never `<Plot data=…>`? Are geoms `Plot.*`/`Geom*`?
+2. Are channels right for each geom — `fill` (Bar/Area/Box/Violin/Pie) vs `color`
+   (Line/Scatter/Bubble), with `group`/`fill`/`color` present wherever `position` stacks/dodges?
+3. Is `position` used instead of the boolean `stack`? Does every stack/fill have a group field?
+   Do horizontal stacks render correctly?
+4. Is opacity expressed as `alpha` (not `opacity`)?
+5. Are literal colours (tokens) used deliberately, and field colours where grouping is intended —
+   no accidental `#888` fallbacks or flattened series?
+6. Is colour/pattern/symbol customization done via `createChartPreset` + `ChartProvider` (context,
+   nested to scope) — not an invented `palette`/`preset` prop?
+7. If a NEW palette/pattern/symbol was added, is it in the correct registry AND named in a preset?
+8. Is there a colour-independent encoding (pattern) where accessibility/print matters, and are
+   interactive charts keyboard/aria-enabled?
+9. Does the chart hold up in light AND dark mode (no invisible marks, no overflow)?
+
+## Procedure
+
+Navigate with the **sensei MCP tools first** — they use the indexed code graph and return richer
+results than blind grep. Fall back to Grep/Glob only if a tool errors or returns empty, and say so.
+
+1. `get_project_summary()` + `get_project_conventions()` — establish stack, structure, and house
+   style. `get_rules()` — honor any project rules.
+2. Locate the chart usage. Read each `PlotChart`/prebuilt-shape/`Plot.*` site and any
+   `ChartProvider`/`createChartPreset` wiring. Record the geoms, channels, `position`,
+   `orientation`, `alpha`, and preset config.
+3. Grep the app's `.svelte` for the smells: `<Plot ` (stale root), `<GeomBar`/`<GeomLine` used as a
+   root, `opacity=` on a chart, `stack\b` as a boolean prop, `palette=` / `preset=` on a chart,
+   raw `#[0-9a-fA-F]{3,8}`/`oklch(`/`rgb(` inside chart props. Map each hit to the correct
+   channel/preset fix.
+4. If a new palette/pattern/symbol was added, verify it's in the right registry (`palette.json` /
+   `PATTERNS` / `SYMBOL_*`) with the right shape, and referenced by name in a preset. Run
+   `rokkit doctor` if available and fold in its advisories.
+
+## Verification evidence (required)
+
+Do not report a verdict without pasting **real output** from commands you ran:
+
+1. **Build** — run the app's build (e.g. `bun run build`, or its documented equivalent). Paste the
+   final status lines. A build that fails on a bad channel/preset/import is a FAIL.
+2. **Chart snapshots** — drive Playwright to capture the reviewed charts in **light and dark** (and
+   any skins the app ships). Paste the command and the pass/fail summary; call out any chart that
+   does not visibly reskin, has invisible/`#888` marks, drops a series' fill, or overflows its axis
+   (e.g. a stack with no group field).
+
+If you cannot run a step, say so explicitly and mark the affected criteria unverified — never imply
+evidence you don't have. A piped/`| tail` exit status reports the pipe, not the command: read the
+real exit status before calling it green.
+
+## Report Format
+
+- **Summary** — one paragraph: what you reviewed and the headline result.
+- **Usage findings** — a table: `file:line` · the issue (stale `<Plot>` root, `opacity` vs `alpha`,
+  `stack` boolean, missing group field, literal-vs-field colour) · the fix.
+- **Preset & customization wiring** — findings on `ChartProvider`/`createChartPreset` usage and any
+  new palette/pattern/symbol registration (or an invented `palette`/`preset` prop to remove).
+- **Accessibility** — colour-only encodings that need a `pattern`, and keyboard/aria gaps.
+- **Verification evidence** — the pasted build output + Playwright snapshot summary (light/dark).
+- **### Verdict PASS/FAIL** — PASS only when usage and preset wiring are correct, no stale/raw
+  smells remain in the reviewed scope, and the build + snapshots are green. Otherwise FAIL with the
+  blocking items listed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/cli",
-  "version": "1.3.9",
+  "version": "1.3.11",
   "description": "Command line utilities for icon bundling and conversion.",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@mdi/svg": "^7.4.47",
-    "@rokkit/unocss": "1.3.9",
+    "@rokkit/unocss": "1.3.11",
     "sade": "^1.8.1",
     "@iconify/tools": "5.0.3",
     "@iconify/types": "^2.0.0",

package/skills/charts-rokkit/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: charts-rokkit
+description: Use when building, styling, customizing, or theming data visualizations with @rokkit/chart in a Svelte 5 app — the ggplot-style geom/aesthetic model (fill/color/pattern/group/size/symbol/alpha/position/orientation + literal-colour tokens), the PlotChart root + Plot.* geom namespace and prebuilt chart shapes, the spec API, and the preset system (colors/patterns/symbols via createChartPreset + ChartProvider, plus how to ADD a new colour palette, pattern, or symbol to the library).
+---
+
+# Charts — Rokkit (`@rokkit/chart`)
+
+`@rokkit/chart` is an SVG charting layer with one rendering path: every chart resolves to a
+reactive `PlotState` that a `PlotChart` renders. It follows ggplot2's grammar — you map **data
+fields** to **aesthetic channels** on **geoms**, and a **preset** supplies the colours, patterns,
+and symbols. There is no per-chart `palette` array prop; customization goes through the preset.
+
+```text
+data + channels (or spec)
+   → PlotState  (scales, colorMap, patternMap, symbolMap, geom registry, selection, zoom)
+   → PlotChart  (SVG: geoms + axes + grid + legend + tooltip + overlays)
+
+preset (colors / patterns / symbols / shades / opacity)
+   → assignColors / assignPatterns / assignSymbols  → the maps PlotState hands to geoms
+```
+
+Design reference: `docs/design/20-chart.md` (architecture) and `docs/design/22-chart-preset.md`
+(preset system). Live explorer: `/app/chart` in the learn app.
+
+---
+
+## Three ways to render a chart
+
+**1. Prebuilt shape** (declarative shorthand — one geom, named channels):
+
+```svelte
+<script>
+  import { BarChart } from '@rokkit/chart'
+</script>
+<BarChart {data} x="quarter" y="revenue" fill="product" position="stack" legend />
+```
+
+Shapes: `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `ScatterPlot`, `BubbleChart`, `BoxPlot`,
+`ViolinPlot`, `Sparkline`.
+
+**2. Compose geoms** under a `PlotChart` root (multi-geom overlays, custom encodings):
+
+```svelte
+<script>
+  import { PlotChart, Plot } from '@rokkit/chart'
+</script>
+<PlotChart {data} width={640} height={360} legend>
+  <Plot.Bar x="quarter" y="revenue" fill="product" position="dodge" />
+  <Plot.Line x="quarter" y="forecast" color="var(--accent)" />
+</PlotChart>
+```
+
+`Plot` is a **namespace object** (`Plot.Bar`, `Plot.Line`, …), not a component — the root is
+`PlotChart`. Each member equals its `Geom*` export (`Plot.Bar === GeomBar`); use either. Full set:
+`Bar`, `Line`, `Area`, `Point`, `Jitter`, `Arc`, `Box`, `Violin`, `Heatmap`, `Hexbin`,
+`Candlestick`, `Waterfall`, `Ribbon`, `Rule`, plus overlays `Highlight` / `Trend`.
+
+**3. Spec API** (full control from a plain object — same result as composition):
+
+```svelte
+<PlotChart {data} spec={{
+  geoms: [
+    { type: 'bar',  channels: { x: 'quarter', y: 'revenue', fill: 'product' }, stat: 'sum' },
+    { type: 'line', channels: { x: 'quarter', y: 'forecast', color: 'class' } }
+  ]
+}} />
+```
+
+---
+
+## Aesthetic channels
+
+Map data fields to visual encodings. Most channels take a **field name**; the palette assigns one
+value per distinct field value.
+
+| Channel | Encoding | Applies to |
+| --- | --- | --- |
+| `x` / `y` | Position | all (Arc uses `theta`/`y` for the slice value) |
+| `fill` | Interior colour-group (field) | Bar / Area / Box / Violin / Pie / Heatmap |
+| `color` | Outline/stroke colour-group (field) | Line / Scatter / Bubble — `fill` falls back to `color` |
+| `pattern` | Texture-fill (field) | Bar / Area / Box / Violin / Pie |
+| `group` | Sub-series field for stack/dodge | Bar / Area (defaults to `fill ?? color`) |
+| `size` | Point radius (field) | Point / Bubble |
+| `symbol` | Point shape (field) | Point |
+| `alpha` | Fixed opacity `0–1` (the single opacity knob) | all geoms |
+| `position` | `dodge` (Bar default) · `stack` · `fill` (100%) · `identity` | Bar / Area |
+| `orientation` | `vertical` (default) · `horizontal` | Bar |
+
+**`position`** — `dodge` side-by-side, `stack` cumulative (axis grows to the total), `fill`
+normalised to 100% (read share), `identity` overlaid. Supersedes the old boolean `stack` prop
+(`stack` is a deprecated alias). Works under `orientation="horizontal"`.
+
+**Literal colours** — a `fill`/`color` value that is a CSS colour (`var(--token)`, `oklch(…)`,
+`#hex`, `currentColor`) is painted **directly** as the mark's fill/stroke instead of being read as
+a field (no group-by, no palette lookup). Works on every geom — colour a series straight from a
+design token:
+
+```svelte
+<Plot.Bar x="q" y="rev" fill="var(--primary)" />   <!-- one token-coloured series -->
+<Plot.Line x="q" y="rev" color="oklch(60% 0.2 250)" />
+```
+
+---
+
+## The preset — colours, patterns, symbols
+
+Every categorical encoding is driven by a **preset** (`packages/chart/src/lib/preset.js`). The
+`defaultPreset`:
+
+```js
+{
+  colors:  ['blue','emerald','rose','amber','violet','sky','pink','teal', … 14 palette NAMES],
+  shades:  { light: { fill: '300', stroke: '700' }, dark: { fill: '500', stroke: '200' } },
+  opacity: { area: 0.6, box: 0.5, violin: 0.5, point: 0.8, … },  // per-geom default; `alpha` overrides
+  patterns:['diagonal','dots','triangles', … 21 pattern NAMES],
+  symbols: ['circle','square','triangle','diamond','cross','star']
+}
+```
+
+Each list is **names into a registry**, cycled across your data's distinct values:
+
+- `colors` → palette names in **`lib/palette.json`** (each name → 11 shades `50–950`).
+  `assignColors(values, mode, preset)` picks `palette[name][shades[mode].fill|stroke]` — so a chart
+  re-colours correctly for light/dark automatically.
+- `patterns` → names in **`patterns/patterns.js`** (`PATTERNS`, the SVG mark defs).
+- `symbols` → names in **`lib/brewing/marks/points.js`** (`SYMBOL_NAMES` ↔ `SYMBOL_TYPES`).
+
+### Selecting / reordering a set at runtime (no library change)
+
+Build a preset with `createChartPreset()` (deep-merges with the default — partial overrides work)
+and share it via `ChartProvider`:
+
+```svelte
+<script>
+  import { ChartProvider, createChartPreset, BarChart, LineChart } from '@rokkit/chart'
+  const preset = createChartPreset({
+    colors: ['teal', 'orange', 'rose'],   // subset/reorder of palette.json names
+    patterns: ['dots', 'hatch'],
+    shades: { dark: { fill: '400' } }      // partial shade override (merges)
+  })
+</script>
+
+<ChartProvider {preset}>
+  <BarChart … />
+  <LineChart … />
+</ChartProvider>
+```
+
+**There is no per-chart `preset` prop.** Preset resolution is context-only: `PlotState` reads the
+`'chart-preset'` context, falling back to `defaultPreset`. To override for one chart or a subtree,
+**nest another `<ChartProvider>`**. Separately, a **named** preset (`'default'` / `'accessible'` /
+`'print'`, or one registered via `helpers.presets`) can be selected through `spec.preset`.
+
+---
+
+## Customization recipes
+
+### Add a NEW colour palette
+
+1. Add an 11-shade entry to `packages/chart/src/lib/palette.json` (shades `50`→`950`, light→dark):
+
+   ```json
+   "brand": { "50": "#f4f7ff", "100": "…", "300": "#93b4ff", "500": "#3b6cff",
+              "700": "#1f45c8", "900": "#122a78", "950": "#0b1a4d" }
+   ```
+
+2. Reference the name in a preset's `colors` and provide it via `ChartProvider`:
+
+   ```js
+   createChartPreset({ colors: ['brand', 'emerald', 'rose'] })
+   ```
+
+   `shades[mode].fill|stroke` decides which stops become the fill/stroke per mode — pick shades
+   that keep text/marks legible on the paper in both light and dark.
+
+### Add a NEW pattern
+
+1. Add an entry to `PATTERNS` in `packages/chart/src/patterns/patterns.js`. A pattern is an array
+   of SVG marks in unit (0–1) tile coordinates (`DefinePatterns.svelte` renders them into
+   `<defs>`):
+
+   ```js
+   crosshatch: [
+     { type: 'line', x1: 0, y1: 0, x2: 1, y2: 1 },
+     { type: 'line', x1: 1, y1: 0, x2: 0, y2: 1 }
+   ]
+   ```
+
+2. Reference `'crosshatch'` in a preset's `patterns`, and set a geom's `pattern` channel to a field
+   (or enable "Pattern fill" in the demo). Patterns are the accessibility/print fallback when
+   colour alone is insufficient.
+
+### Add a NEW symbol
+
+1. In `packages/chart/src/lib/brewing/marks/points.js`, add a d3 symbol generator to `SYMBOL_TYPES`
+   and its label to `SYMBOL_NAMES` **at the same index** (import the type from `d3-shape`, e.g.
+   `symbolWye`):
+
+   ```js
+   const SYMBOL_TYPES = [symbolCircle, symbolSquare, …, symbolWye]
+   const SYMBOL_NAMES = ['circle', 'square', …, 'wye']
+   ```
+
+2. Reference `'wye'` in a preset's `symbols`; set a Point/Scatter geom's `symbol` channel to a
+   field to encode a category as shape.
+
+### Theme the mark colours without changing data-grouping
+
+Use a literal `fill`/`color` (design token) on the geom for a fixed colour, or override
+`--chart-*` CSS variables for overlays/decorations (grid/trend/highlight/selected). Marks and
+decorations expose `data-*` hooks: `[data-plot-geom="<type>"]`, `[data-plot-element]`
+(`data-fill`/`data-group`), `[data-plot-grid-line]`, `[data-plot-trend]`, `[data-plot-highlight]`,
+`[data-plot-selected]`.
+
+---
+
+## Stats, interaction, and extras
+
+- **Stats** — `stat` aggregates rows sharing an x before rendering: `identity` (default), `sum`,
+  `mean`, `min`, `max`, `count`, `median`. Box/violin use a quartile `box` stat. Register custom
+  stats via `helpers.stats` (`{ p90: (values) => quantile(values, 0.9) }`).
+- **Selection** — set `onselect`/`selectable` on `PlotChart` to make marks clickable +
+  keyboard-activatable; `selected` is `$bindable`. Selected marks carry `data-plot-selected`.
+- **Overlays** — `highlight` (mark first/last/min/max/index/predicate) and `trend` (mean/median/
+  min/max/value or fitted linear/ma/ema/exp) render above the geoms without affecting scales.
+- **Layout & motion** — `Sparkline` (inline, no axes), `FacetPlot` (small multiples by a facet
+  field), `AnimatedPlot` (frame-based over a time field), `CrossFilter` (linked filtering),
+  `ChartExporter` (SVG/PNG export).
+- **Grid / zoom / tooltip** — `grid: boolean|'x'|'y'|'both'`, `zoom`, `tooltip` on the root.
+
+---
+
+## Gotchas
+
+- The root is **`PlotChart`**, not `<Plot>` — `Plot` is the geom namespace object.
+- **No `palette` prop and no per-chart `preset` prop** — customise via `createChartPreset` +
+  `ChartProvider` (nest to scope), or `spec.preset` for named presets.
+- `alpha` is the single opacity knob (a fixed `0–1` on the geom/root); it overrides the preset's
+  per-geom `opacity` defaults. There is no `opacity` prop.
+- `position="stack"` supersedes the boolean `stack` prop; grouping needs a `fill`/`color`/`group`
+  field (a stack with no group field renders individual bars, not a stacked total).
+- A literal colour on `fill`/`color` is applied directly — it is **not** a legend group.
+
+## Verify
+
+- Live: `/app/chart` — switch type and tweak orientation / position / colour / fill / pattern /
+  opacity, and read the emitted `Plot.*` usage.
+- Types + lint: `bun run check` (or `bun run lint`); chart unit tests: `bun run test:ci --project chart`.