-
-
Four business charts
Returns split at zero, profit bars, cash flows with a tooltip, and a sparkline. |
-
Pie and radar
A doughnut with its total in the centre, and a radar comparing two strategies. |
-
Heatmap
Six months of activity, and orders by hour and weekday. |
-
-
-
Scatter
One point per trade, with per-point shape and colour and a single-point readout. |
-
Stacked horizontal bars
Stacked bars in horizontal orientation, with titled axes. |
-
Floating bars and bands
A waterfall chart, and a forecast band with error bars. |
-
-
-
Range selector
Three series over five months, with a range selector below. |
-
Synchronised crosshair
Balance and profit panels sharing one crosshair. |
-
Depth chart
Cumulative bid and ask depth. |
-
-
-
Depth chart modes
Cumulative, histogram, combined and ladder modes. |
-
The bid/ask ratio bar
The balance of bid and ask volume, below the depth chart. |
- |
-
-
-
-### Order flow and derivatives
-
-
-
-
Market profile
Time at price as TPO letters, with the point of control and value area. |
-
Footprint
Bid and ask volume at every price, inside each candle. |
-
Order-book heatmap
Resting liquidity over time, with walls as bright lines. |
-
-
-
Cumulative delta
Running delta over a session, with buying and selling per bar. |
-
Liquidity map
Where the leveraged stops sit, longs below the price and shorts above. |
-
Open interest and funding
How much money is in the trade, and which side is paying. |
-
-
-
Options payoff
A bull call spread and a long straddle at expiry, with break-evens. |
-
Volatility curves
A smile at three expiries, and a term structure. |
-
Pair spread
The log ratio of two symbols, with bands and a z-score. |
-
-
-
-### Backtests and results
-
-
-
-
Equity curve
The curve, with the underwater drawdown panel beneath it. |
-
Monte Carlo fan
Simulated paths as percentile bands, with the odds of loss and ruin. |
-
R-multiple distribution
Results in R, with expectancy, profit factor and SQN. |
-
-
-
Trade timeline
Every trade from entry to exit, a lane per symbol. |
-
Seasonality
Returns by month and year, compounded, with totals and averages. |
-
Calendar
Daily profit and loss on real month panels. |
-
-
-
Waterfall
A balance built up step by step, from opening to closing. |
- |
- |
-
-
-
-### Dashboards and reports
-
-
-
-
Treemap
A market map of sectors and symbols, and portfolio weight. |
-
Sunburst
A hierarchy as rings, with the total in the middle. |
-
Sankey
Fee income flowing through revenue into costs and profit. |
-
-
-
Chord
Flow between venues, both ways round a ring. |
-
Marimekko
Two dimensions at once: column width and cell height. |
-
Stream graph
Two years of composition, on a wiggle baseline. |
-
-
-
Parallel coordinates
Five strategies compared on five measures at once. |
-
Slope and bump
Returns by quarter, by value and by changing rank. |
-
Bubble
Risk against return, sized by capital. |
-
-
-
Box plot
Quartiles, whiskers and outliers for four strategies. |
-
Histogram
Daily returns split at zero, and a spread of trade sizes. |
-
Violin and ridgeline
The shape of a distribution, side by side or stacked. |
-
-
-
Dumbbell
Two values a row, joined by a bar. |
-
Bullet
KPIs against their targets, on banded tracks. |
-
Gauge
A dial with coloured ranges, a half circle and a progress ring. |
-
-
-
Waffle
Shares as a hundred squares, counted rather than judged. |
-
Funnel
Where the people go, tapered or straight-sided. |
-
Sparkline grid
A watchlist of small multiples, a name and a shape each. |
-
-
-
-### Chart types
-
-
-
-
29 drawing tools
Labelled trend and horizontal lines, with snapping and persistence. |
-
Rays, boxes and Fibonacci
A ray, an arrow, a horizontal ray, a range box and a Fibonacci retracement. |
-
The line editor
Controls for the selected drawing, customisable through DrawingStyle. |
-
-
-
Orders and positions
A working order and an open position, each labelled on the axis. |
-
Planning a trade
A planned position with risk-to-reward, inside a channel. |
-
Event marks
Earnings, dividend, split and news markers below the candles. |
-
-
-
-### Interaction and navigation
-
-
-
-## Overview
-
-`ohlcv_chart` covers both the trading screen and the balance, growth and
-reporting charts that surround it, in a single dependency. The name refers to
-the open, high, low, close and volume data the candlestick chart renders.
-
-The entire package is free, including for commercial use. Every chart type,
-indicator and drawing tool is included; there is no paid tier.
+Candlestick charts for Flutter, with indicators, drawing tools and a library of
+other chart types. Pure `CustomPainter` — no WebView, no JavaScript bridge.
+Free for any use, with no paid tier.
+
+
+
+
Four business charts
Returns split at zero, profit bars, cash flows with a tooltip, and a sparkline. |
+
Pie and radar
A doughnut with its total in the centre, and a radar comparing two strategies. |
+
Heatmap
Six months of activity, and orders by hour and weekday. |
+
+
+
Scatter
One point per trade, with per-point shape and colour and a single-point readout. |
+
Stacked horizontal bars
Stacked bars in horizontal orientation, with titled axes. |
+
Floating bars and bands
A waterfall chart, and a forecast band with error bars. |
+
+
+
Range selector
Three series over five months, with a range selector below. |
+
Synchronised crosshair
Balance and profit panels sharing one crosshair. |
+
Depth chart
Cumulative bid and ask depth. |
+
+
+
Depth chart modes
Cumulative, histogram, combined and ladder modes. |
+
The bid/ask ratio bar
The balance of bid and ask volume, below the depth chart. |
+ |
+
+
+
+## Order flow and derivatives
+
+
+
+
Market profile
Time at price as TPO letters, with the point of control and value area. |
+
Footprint
Bid and ask volume at every price, inside each candle. |
+
Order-book heatmap
Resting liquidity over time, with walls as bright lines. |
+
+
+
Cumulative delta
Running delta over a session, with buying and selling per bar. |
+
Liquidity map
Where the leveraged stops sit, longs below the price and shorts above. |
+
Open interest and funding
How much money is in the trade, and which side is paying. |
+
+
+
Options payoff
A bull call spread and a long straddle at expiry, with break-evens. |
+
Volatility curves
A smile at three expiries, and a term structure. |
+
Pair spread
The log ratio of two symbols, with bands and a z-score. |
+
+
+
Volatility surface
Implied volatility across strike and expiry, with the skew against the money. |
+
Futures curve
Prices by delivery month, with contango or backwardation read off. |
+ |
+
+
+
+## Backtests and results
+
+
+
+
Equity curve
The curve, with the underwater drawdown panel beneath it. |
+
Monte Carlo fan
Simulated paths as percentile bands, with the odds of loss and ruin. |
+
R-multiple distribution
Results in R, with expectancy, profit factor and SQN. |
+
+
+
Trade timeline
Every trade from entry to exit, a lane per symbol. |
+
Seasonality
Returns by month and year, compounded, with totals and averages. |
+
Calendar
Daily profit and loss on real month panels. |
+
+
+
Waterfall
A balance built up step by step, from opening to closing. |
+
MAE / MFE scatter
Every trade by how far it went against you or for you, and what it made. |
+
Value at risk
Returns with the loss tail picked out, and VaR and expected shortfall marked. |
+
+
+
Efficient frontier
Portfolios by risk and return, with the frontier and the best Sharpe ratio. |
+
Activity clock
A week as a clock face: an hour round the dial, a weekday on each ring. |
+ |
+
+
+
+## Dashboards and reports
+
+
+
+
Treemap
A market map of sectors and symbols, and portfolio weight. |
+
Sunburst
A hierarchy as rings, with the total in the middle. |
+
Sankey
Fee income flowing through revenue into costs and profit. |
+
+
+
Chord
Flow between venues, both ways round a ring. |
+
Marimekko
Two dimensions at once: column width and cell height. |
+
Stream graph
Two years of composition, on a wiggle baseline. |
+
+
+
Parallel coordinates
Five strategies compared on five measures at once. |
+
Slope and bump
Returns by quarter, by value and by changing rank. |
+
Bubble
Risk against return, sized by capital. |
+
+
+
Box plot
Quartiles, whiskers and outliers for four strategies. |
+
Histogram
Daily returns split at zero, and a spread of trade sizes. |
+
Violin and ridgeline
The shape of a distribution, side by side or stacked. |
+
+
+
Dumbbell
Two values a row, joined by a bar. |
+
Bullet
KPIs against their targets, on banded tracks. |
+
Gauge
A dial with coloured ranges, a half circle and a progress ring. |
+
+
+
Waffle
Shares as a hundred squares, counted rather than judged. |
+
Funnel
Where the people go, tapered or straight-sided. |
+
Sparkline grid
A watchlist of small multiples, a name and a shape each. |
+
+
+
+## Progress and goals
+
+
+
+
Training curves
Loss and accuracy of runs, smoothed, with the best checkpoint and divergence marked. |
+
Scaling laws
Loss against compute on log-log axes, with the power law fitted and extrapolated. |
+
Hyperparameter sweep
A learning-rate by batch-size grid, the best combination starred. |
+
+
+
Training timeline
Jobs by machine, coloured by how each finished. |
+
Benchmark matrix
Models against benchmarks, coloured by standing, leaders starred. |
+
Model cost against quality
Models by price and score, with the Pareto frontier. |
+
+
+
Latency bands
p50, p95 and p99 over a day, with an objective and its breaches. |
+
Token usage
Cached, input and output tokens, with the cost as a line. |
+
Evaluation breakdown
Pass rate by category, worst first, with a threshold. |
+
+
+
Token heatmap
A completion with each token shaded by its surprisal. |
+ |
+ |
+
+
+
+## Chart types
+
+
+
+
29 drawing tools
Labelled trend and horizontal lines, with snapping and persistence. |
+
Rays, boxes and Fibonacci
A ray, an arrow, a horizontal ray, a range box and a Fibonacci retracement. |
+
The line editor
Controls for the selected drawing, customisable through DrawingStyle. |
+
+
+
Orders and positions
A working order and an open position, each labelled on the axis. |
+
Planning a trade
A planned position with risk-to-reward, inside a channel. |
+
Event marks
Earnings, dividend, split and news markers below the candles. |
+
+
+
+## Interaction and navigation
+
+
+
+Back to the [documentation index](README.md).
diff --git a/doc/latency-band-chart.md b/doc/latency-band-chart.md
new file mode 100644
index 0000000..b937f0b
--- /dev/null
+++ b/doc/latency-band-chart.md
@@ -0,0 +1,61 @@
+# Latency bands
+
+
+
+`LatencyBandChart` shows an inference service's latency over time as **bands**:
+the median as a line, the span up to the 95th percentile and on to the 99th
+shaded, an **objective** drawn across, and the intervals that broke it marked.
+The tail is what users feel, and a median line alone hides it.
+
+```dart
+LatencyBandChart(
+ samples: [
+ for (final w in windows)
+ LatencySample(time: w.start, p50: w.p50, p95: w.p95, p99: w.p99),
+ ],
+ slo: 1200,
+ valueFormatter: (ms) => '${ms.round()} ms',
+);
+```
+
+The chart fills its constraints. When the height is unbounded, it uses
+`defaultHeight`.
+
+## Samples
+
+| Field | Description |
+| --- | --- |
+| `time` | When the interval began |
+| `p50`, `p95`, `p99` | The latencies, in one unit of your choice |
+| `data` | App data, returned on touch |
+
+A sample with a value that is not finite is left out of the lines and the bands.
+
+## The objective
+
+`slo` draws a dashed line, and `sloPercentile` says which percentile it is set
+on — `p95` by default. Every interval whose percentile is over it gets a red
+mark on the bottom of the plot, and is flagged `breached` on touch.
+
+| Function | Description |
+| --- | --- |
+| `sloBreaches(samples, slo, percentile:)` | The indices of the intervals over the objective |
+
+An interval exactly on the objective is within it.
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `logY` | A logarithmic axis, for a tail far above the median |
+| `medianColor`, `p95Color`, `p99Color`, `sloColor`, `breachColor` | Colours |
+| `lineWidth`, `showLegend`, `showBreaches` | Line weight, the legend and the marks |
+| `valueFormatter`, `timeFormatter`, `yAxisTitle` | Axes |
+
+## Touch
+
+`onTouch` reports a `LatencyTouchDetails` with the `sample`, its `index` and
+whether it `breached`, and `null` when the pointer leaves. `tooltipBuilder`
+builds a card beside the crosshair.
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/mae-mfe-chart.md b/doc/mae-mfe-chart.md
new file mode 100644
index 0000000..e71a20d
--- /dev/null
+++ b/doc/mae-mfe-chart.md
@@ -0,0 +1,81 @@
+# MAE / MFE scatter
+
+
+
+`MaeMfeChart` puts every trade on a plane by how far it went against you (maximum
+adverse excursion, MAE) or for you (maximum favourable excursion, MFE), and what
+it finally made. It is the picture system designers use to place a stop and a
+target: if few winners ever went deep against the position, a tight stop costs
+little.
+
+```dart
+MaeMfeChart(
+ trades: [
+ for (final t in backtest.trades)
+ TradeExcursion(pnl: t.r, mae: t.maxAdverseR, mfe: t.maxFavourableR),
+ ],
+ xReferenceLines: const [1], // the stop in use
+);
+```
+
+The chart fills its constraints. When the height is unbounded, it uses
+`defaultHeight`.
+
+## Trades
+
+| Field | Description |
+| --- | --- |
+| `pnl` | What the trade made or lost, in R, points or money |
+| `mae` | How far it went against the position, as a distance of zero or more |
+| `mfe` | How far it went in the position's favour, as a distance of zero or more |
+| `label`, `color`, `data` | Name, a colour of its own, and app data returned on touch |
+
+`mae`, `mfe` and `pnl` are all in the same unit.
+
+## Which excursion
+
+`kind: ExcursionKind.adverse` (the default) puts the MAE along the bottom axis.
+`ExcursionKind.favourable` puts the MFE there. Winners and losers take
+`winnerColor` and `loserColor`.
+
+A line marks the limit no trade can pass: a result never beats its favourable
+excursion, nor loses more than its adverse one, so every dot sits on one side
+of it. `showLimit: false` hides it, and `showZeroLine` marks a result of zero.
+`xReferenceLines` marks excursions such as the stop in use or a target.
+
+## Numbers
+
+| Function | Description |
+| --- | --- |
+| `ExcursionStats.fromTrades(trades)` | Count, winners, losers, average MAE and MFE, and `edgeRatio` |
+| `winnersStoppedAt(trades, stop)` | How many winners a stop `stop` away would have taken out first |
+| `excursionRange(trades, kind)` | The ranges the chart would pick |
+| `layOutExcursions(...)` / `excursionDotAt(...)` | The dots it paints, and a hit test; both usable without a widget |
+
+`edgeRatio` is the average MFE over the average MAE: above 1 the market moved
+more for the positions than against them.
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `dotRadius`, `dotOpacity` | Size of a dot, and how opaque; a crowd shows where it is densest |
+| `limitColor`, `referenceColor` | Colours of the limit line and the reference lines |
+| `showAxes`, `axisWidth`, `axisHeight`, `tickCount` | The axes and their room |
+| `xFormatter`, `yFormatter`, `axisLabelStyle` | Axis labels |
+| `xAxisTitle`, `yAxisTitle`, `axisTitleStyle` | Axis titles; the bottom one names the excursion by default |
+| `gridColor` | Grid ruled at each tick; `null` rules none |
+| `hoverBorder`, `backgroundColor`, `padding` | Hover ring, background, space around the chart |
+
+## Touch
+
+`onTouch` reports an `ExcursionTouchDetails` with the `dot` and its `trade`, and
+`null` when the pointer leaves. `tooltipBuilder` builds a card beside the dot.
+
+## Animation
+
+`animationDuration` grows the dots in; `animationCurve` eases it and
+`animateOnMount` controls the first build. The chart animates again only when
+the trades' values change, not when the same numbers arrive in a new list.
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/model-pareto-chart.md b/doc/model-pareto-chart.md
new file mode 100644
index 0000000..35f3813
--- /dev/null
+++ b/doc/model-pareto-chart.md
@@ -0,0 +1,67 @@
+# Model cost against quality
+
+
+
+`ModelParetoChart` plots models by what they cost and how good they are, and
+traces the **Pareto frontier** through the ones nothing beats: the cheapest way
+to get each level of quality. Models off the frontier are drawn faintly, and
+touching one says what the same money buys instead.
+
+```dart
+ModelParetoChart(
+ models: const [
+ ModelPoint(name: 'Large', cost: 15, score: 88, size: 200000, group: 'A'),
+ ModelPoint(name: 'Small', cost: 0.25, score: 71, size: 128000, group: 'A'),
+ ModelPoint(name: 'Open 70B', cost: 0.9, score: 79, group: 'B'),
+ ],
+ costFormatter: (v) => '\$${v}',
+ xAxisTitle: 'Price per 1M tokens',
+ yAxisTitle: 'MMLU',
+);
+```
+
+The chart fills its constraints. When the height is unbounded, it uses
+`defaultHeight`.
+
+## Models
+
+| Field | Description |
+| --- | --- |
+| `name` | What the model is called |
+| `cost` | What it costs — a price per million tokens, a latency, a parameter count. Lower is better |
+| `score` | How good it is. Higher is better |
+| `size` | What the bubble's **area** shows, such as the context window; null draws every bubble alike |
+| `group` | A family or provider; models of a group share a palette colour |
+| `color`, `data` | A colour of its own, and app data returned on touch |
+
+## The frontier
+
+`paretoIndices(models)` returns the indices of the models on it, by rising cost.
+A model is on it when none is both cheaper and better. Of two models at one cost
+only the higher score is on it. A model whose cost or score is not finite is
+never on it.
+
+## Axes
+
+`logCost` (on by default) puts cost on a logarithmic axis, since prices span
+decades; a model whose cost is zero or less is then not drawn. Turn it off for a
+linear axis.
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `minRadius`, `maxRadius` | The radii the sizes are spread between |
+| `palette` | Colours taken in turn by groups |
+| `showFrontier`, `frontierColor`, `dimOpacity` | The frontier line, and how faint off-frontier models are |
+| `labelAll`, `labelStyle` | Name every model, not only those on the frontier |
+| `showLegend`, `legendStyle` | The groups, in the corner |
+| `costFormatter`, `scoreFormatter`, `xAxisTitle`, `yAxisTitle` | Axes |
+
+## Touch
+
+`onTouch` reports a `ModelTouchDetails` with the `model`, whether it is
+`onFrontier`, and — for one that is not — `beatenBy`: the best frontier model
+that costs no more. `null` when the pointer leaves.
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/progress-bars.md b/doc/progress-bars.md
new file mode 100644
index 0000000..c556320
--- /dev/null
+++ b/doc/progress-bars.md
@@ -0,0 +1,103 @@
+# Progress bars and cards
+
+
+
+`ProgressBars` shows how far each of several things has got. Every row is a
+label and a figure above a bar; the bar is a pill, a block or a row of cells,
+and can carry a mark for where it should be by now.
+
+```dart
+ProgressBars(
+ items: const [
+ ProgressItem(label: 'Net profit', value: 72, target: 60),
+ ProgressItem(label: 'Trades taken', value: 32, total: 50),
+ ],
+ shape: ProgressShape.pill,
+);
+```
+
+The chart fills the width it is given. In a box with no height it takes
+`intrinsicHeight`; in a box too short for its rows they shrink together to fit.
+
+## An item
+
+| Field | What it is |
+| --- | --- |
+| `label` | Written above the bar at the left |
+| `value`, `total` | How far it has got, out of what; `total` defaults to 100 |
+| `target` | A mark across the bar, in the same units as `total` |
+| `color` | Overrides the chart's fill colour for this row |
+| `valueLabel` | Written above the bar at the right; null writes the per cent done |
+
+A value past `total` fills the bar and no more; a value that is not a number,
+or a `total` of zero or less, fills nothing.
+
+## Shapes
+
+| `ProgressShape` | Look |
+| --- | --- |
+| `pill` | One bar with fully round ends |
+| `block` | One bar with a small corner radius |
+| `segmented` | `segments` separate cells, `segmentGap` apart, filled from the left and the last one part way |
+
+A short fill keeps the track's rounded left end rather than floating inside it.
+
+## Layout
+
+`layOutProgress(items, size:, ...)` is the layout on its own. It returns a
+`ProgressLayout` of `ProgressRowLayout`s, each with `rowRect`, `headerRect`,
+`trackRect`, `fillRect` and `targetX`; `layout.rowAt(point)` finds the row under
+a point. `progress` shortens every fill for a draw-in animation and leaves the
+targets where they are.
+
+## Touch
+
+`onItemTap` is called with an item when it is touched or dragged over, and with
+null when the touch leaves. The touched row is highlighted.
+
+## Styling
+
+| Field | Default |
+| --- | --- |
+| `color` | A blue, where a row names no colour |
+| `trackColor`, `targetColor` | A faint grey, and a near-white mark |
+| `barHeight`, `headerHeight`, `headerGap`, `rowGap` | 10, 18, 6 and 16 |
+| `showValues`, `valueFormatter` | The figure written at the right of the header |
+| `labelStyle`, `valueStyle` | 12 px, grey and white |
+| `animationDuration`, `animationCurve`, `animateOnMount` | The draw-in |
+
+`semanticLabel` is what a screen reader announces for the chart.
+
+## Progress card
+
+`ProgressCard` wraps any widget — a course, a goal, a task — in a card whose
+whole background is a progress fill. The card is faintly tinted in `color`
+(`trackOpacity`, 0.08) and a part of it (`fillOpacity`, 0.55) fills in as far as
+`progress`, from 0 to 1, has got. The child is drawn as it is, over the fill,
+and the fill animates to a new `progress` over `animationDuration`.
+
+| `ProgressCardMode` | Fill |
+| --- | --- |
+| `sweep` (default) | A wedge sweeps round the card's centre like a clock, from twelve o'clock and clockwise: half done is the right half. The angle is the progress, so it reads at a glance on a tile |
+| `circle` | A circle grows from the middle of the card's left edge and has reached the far corners at full progress; its curved edge suits a wide card better than a sweep |
+| `linear` | A bar fills the card from its left edge, as wide as the progress; best on a wide, short card |
+
+```dart
+ProgressCard(
+ progress: 12 / 20,
+ mode: ProgressCardMode.sweep,
+ color: Colors.teal,
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text('Technical analysis'),
+ Text('12 of 20 lessons'),
+ ],
+ ),
+);
+```
+
+## See also
+
+- [Bullet](bullet-chart.md) — a measure against a target on a banded track
+- [Gauge](gauge-chart.md) — one value on a dial, or a progress ring
diff --git a/doc/scaling-law-chart.md b/doc/scaling-law-chart.md
new file mode 100644
index 0000000..cf947cb
--- /dev/null
+++ b/doc/scaling-law-chart.md
@@ -0,0 +1,68 @@
+# Scaling laws
+
+
+
+`ScalingLawChart` plots the loss models reached against how much they were given
+— parameters, training tokens or FLOPs — on log-log axes, fits the **power law**
+through them and carries it past the largest model, so the question "what would
+ten times the compute buy?" has a picture.
+
+```dart
+ScalingLawChart(
+ points: [
+ for (final m in runs) ScalingPoint(scale: m.flops, loss: m.loss, label: m.name),
+ ],
+ fitFrom: 1e19, // leave the small models that sit off the law out
+ extrapolateTo: 1e24,
+ targetLoss: 1.8, // where is the line predicted to reach this?
+);
+```
+
+The chart fills its constraints. When the height is unbounded, it uses
+`defaultHeight`.
+
+## The fit
+
+`fitPowerLaw(points)` is a least-squares line through the logarithms of the
+points, `loss = coefficient × scale ^ exponent`:
+
+| Field | Description |
+| --- | --- |
+| `exponent` | The slope on the log-log plot; negative when more scale lowers the loss |
+| `coefficient` | The loss at a scale of 1 |
+| `rSquared` | How much of the variation in log loss the line explains |
+| `logResidual` | The standard deviation of the points' distance from the line, in log10 of the loss |
+| `predict(scale)`, `scaleFor(loss)` | The loss at a scale, and the scale for a loss |
+
+It needs two points at two different scales. A point whose scale or loss is not
+a positive finite number is skipped. The fit is a pure power law with no
+irreducible term, which is a good description over the range where models are
+still improving; `fitFrom` leaves out the small models that sit off it.
+
+## What is drawn
+
+| Mark | Meaning |
+| --- | --- |
+| Dots | The models, named beside them with `showLabels` |
+| Solid line | The fit across the range of the points |
+| Dashed line | The fit carried on to `extrapolateTo` |
+| Band | One residual standard deviation either side of the fit (`showBand`) |
+| Green ring | Where the fit reaches `targetLoss`, with the scale written beside it |
+| Corner text | The law and its R² (`showFitLabel`) |
+
+## Touch
+
+`onTouch` reports a `ScalingTouchDetails` with the `point`, what the fit
+`predicted` there and the `ratio` — 1.1 is a model 10% worse than the law — or
+`null` when the pointer leaves. `tooltipBuilder` builds a card beside the point.
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `pointColor`, `fitColor`, `bandColor`, `targetColor` | Colours |
+| `dotRadius`, `labelStyle` | Point size and label style |
+| `scaleFormatter`, `lossFormatter` | Axis labels; the scale is written as `1e21` by default |
+| `xAxisTitle`, `yAxisTitle`, `axisLabelStyle`, `gridColor` | Axes and grid |
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/sweep-chart.md b/doc/sweep-chart.md
new file mode 100644
index 0000000..50eb418
--- /dev/null
+++ b/doc/sweep-chart.md
@@ -0,0 +1,63 @@
+# Hyperparameter sweep
+
+
+
+`SweepChart` lays a two-setting sweep out as a grid of scores — a learning rate
+across, a batch size down — coloured good to bad, with the **best combination
+starred** and a last column and row holding the **mean** of each setting, which
+is what it is worth whatever the other is set to.
+
+```dart
+SweepChart(
+ trials: [
+ for (final r in runs)
+ SweepTrial(x: r.learningRate, y: r.batchSize, score: r.valLoss),
+ ],
+ xAxisLabel: 'learning rate',
+ yAxisLabel: 'batch size',
+);
+```
+
+The chart fills its constraints. When the height is unbounded, it uses
+`defaultHeight`. It is built on `HeatmapChart`.
+
+## Trials
+
+| Field | Description |
+| --- | --- |
+| `x`, `y` | The two settings; the grid has a column per distinct `x` and a row per distinct `y`, ascending |
+| `score` | The result: a validation loss, an accuracy |
+| `data` | App data, returned on touch |
+
+Trials that share both settings are averaged. A trial whose settings or score
+are not finite is skipped, and a combination nobody tried is an empty square.
+
+## The grid
+
+`sweepGrid(trials, lowerIsBetter:)` returns what the chart draws:
+
+| Member | Description |
+| --- | --- |
+| `xs`, `ys` | The distinct settings |
+| `scores[y][x]`, `counts[y][x]` | The mean score and the trial count of each combination |
+| `bestX`, `bestY`, `best` | The best combination — lowest, or highest with `lowerIsBetter: false` |
+| `columnMeans`, `rowMeans` | The mean score of each setting |
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `lowerIsBetter` | Which end of the scores is good; sets the colour direction too |
+| `goodColor`, `midColor`, `badColor` | The scale |
+| `showMarginals`, `marginalLabel` | The mean column and row |
+| `showValues`, `scoreFormatter` | Scores written in the squares |
+| `xFormatter`, `yFormatter` | Setting labels; `3e-4`, `128` by default |
+| `yAxisWidth`, `xAxisHeight`, `spacing`, `radius` | Layout |
+
+## Touch
+
+`onTouch` reports a `SweepTouchDetails` with the settings `x` and `y`, the
+`score`, the trial `count`, and whether the square `isBest` or a marginal, and
+`null` when the pointer leaves.
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/token-heatmap.md b/doc/token-heatmap.md
new file mode 100644
index 0000000..3330395
--- /dev/null
+++ b/doc/token-heatmap.md
@@ -0,0 +1,130 @@
+# Token heatmap
+
+
+
+`TokenHeatmap` shows a model's text with **each token shaded by a number**:
+where the model was unsure, what a prediction leaned on, which words an
+attribution method found important. Tokens flow and wrap like text, so a
+completion reads as a paragraph with its doubts lit up.
+
+```dart
+TokenHeatmap(
+ tokens: [
+ for (final t in completion.tokens)
+ TokenScore.fromLogProb(
+ t.text,
+ t.logProb,
+ alternatives: [
+ for (final a in t.topLogProbs)
+ TokenAlternative(a.text, exp(a.logProb)),
+ ],
+ ),
+ ],
+ highlightTop: 3,
+ showStrip: true,
+ showSummary: true,
+);
+```
+
+The chart takes the height its text needs. In a box that is shorter, the text is
+cut off. It does not scroll — put it in a scroll view for a long document.
+
+## Tokens
+
+| Member | Description |
+| --- | --- |
+| `TokenScore(token, value)` | A token's text, as the tokenizer produced it, and its score |
+| `probability` | The probability the model gave the token, 0 to 1, for the readout |
+| `alternatives` | `TokenAlternative(token, probability)` — what else the model was weighing, most likely first |
+| `TokenScore.fromLogProb(token, logProb)` | Scores a token by its **surprisal**, `-logProb`: the less likely the model thought it, the higher the score. Sets `probability` too |
+
+A newline inside a token ends the line. Leading spaces are kept, so tokens such
+as `" capital"` read as they were produced. A score that is not finite leaves
+the token uncoloured.
+
+## How it is drawn
+
+Each token is a rounded box with room round its text. A token that begins a word
+— where the tokenizer put a space — sits a little apart from the one before it,
+and one that carries a word on sits close, so the boxes of a word read as a word.
+
+| Parameter | Description |
+| --- | --- |
+| `shading` | `TokenShading.soft` (the default) tints the box and draws a line of the full colour under the text; `TokenShading.solid` fills it with the full colour, the text turning dark or light to suit |
+| `horizontalPadding`, `verticalPadding` | Room round the text inside a box |
+| `wordGap`, `tokenGap` | The gap before a token that begins a word, and before one that carries on |
+| `lineGap`, `tokenRadius` | Space between lines, and the rounding |
+
+## Reading a long text
+
+| Parameter | What it does |
+| --- | --- |
+| `highlightTop: n` | Rings the *n* highest-scoring tokens and numbers them 1 to *n* — the places to look first |
+| `focusAbove: v` | Leaves every token scoring below *v* unshaded and dim, so only the doubtful ones are lit |
+| `showStrip` | A strip of every token's score, in order, above the legend. Over a text longer than the strip is wide, each bar is the highest of the tokens it covers, so a single bad token is never averaged away |
+| `showWhitespace` | Writes spaces as `·` and line breaks as `↵`, to see what the tokenizer really produced |
+| `selectedIndex` | Holds one token outlined, for a selection your app keeps |
+
+The legend marks where the **mean** falls on the scale, and `showSummary` writes
+the mean and the perplexity under it.
+
+## The readout
+
+Touching a token opens a card with its text, its score, its **rank** among the
+tokens (`rank 2 of 28`), the probability the model gave it, and — if you
+supplied them — the alternatives it was weighing instead. It needs no code:
+
+```dart
+TokenHeatmap(tokens: tokens, scoreLabel: 'surprisal')
+```
+
+`scoreLabel` names the score in it, `showReadout: false` turns it off, and
+`tooltipBuilder` replaces it with a card of your own.
+
+## Colour
+
+The default `scale` runs green (confident) through amber to red (surprising),
+which suits surprisals and entropies. For probabilities, where high is
+confident, turn it over:
+
+```dart
+TokenHeatmap(
+ tokens: probabilities,
+ scale: HeatmapGradientScale(colors: [red, amber, green]),
+ minValue: 0,
+ maxValue: 1,
+);
+```
+
+`minValue` and `maxValue` fix the ends of the scale — useful to compare two
+completions on the same colours — and otherwise take the lowest and highest
+score. Text is dark on a light colour and light on a dark one.
+
+## Numbers
+
+| Function | Description |
+| --- | --- |
+| `summarizeTokens(tokens)` | `count`, `mean`, `max`, `maxIndex` and `perplexity` (`exp(mean)`, for surprisals in nats) |
+| `tokenRanks(tokens)` | Each token's rank, 1 for the highest; equal scores share one |
+| `topTokens(tokens, n)` | The indices of the *n* highest, highest first |
+| `binTokenScores(tokens, bins)` | The strip's bars: the highest score of each slice |
+| `flowTokens(tokens, width, measure)` | The `TokenBox`es and the height, without a renderer |
+| `tokenDisplay(token, showWhitespace:)` | How a token is written on screen |
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `textStyle` | The text; 14 px by default — use a monospaced font for code |
+| `tokenRadius`, `verticalPadding`, `lineGap` | The rectangles and the lines |
+| `showLegend`, `lowLabel`, `highLabel`, `legendStyle` | The scale bar |
+| `stripHeight`, `highlightColor`, `dimColor` | The strip, the rings, the dimmed text |
+| `valueFormatter`, `hoverBorder` | Score formatting and the hover outline |
+
+## Touch
+
+`onTouch` reports a `TokenTouchDetails` with the token's `index`, the `token`,
+its `rect`, its `rank` and how many tokens were `scored`, and `null` when the
+pointer leaves.
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/token-usage-chart.md b/doc/token-usage-chart.md
new file mode 100644
index 0000000..32ee5f0
--- /dev/null
+++ b/doc/token-usage-chart.md
@@ -0,0 +1,65 @@
+# Token usage
+
+
+
+`TokenUsageChart` shows what a model served over time: tokens as **stacked
+columns** — cached, input and output — and the **cost** as a line against its
+own axis on the right. The cached share, the part of the prompt that was a cache
+read, is its own colour because it is cheaper and faster than the rest.
+
+```dart
+TokenUsageChart(
+ buckets: [
+ for (final d in days)
+ UsageBucket(
+ time: d.date,
+ inputTokens: d.prompt,
+ outputTokens: d.completion,
+ cachedTokens: d.cacheRead,
+ cost: d.dollars,
+ ),
+ ],
+ costFormatter: (v) => '\$${v.toStringAsFixed(0)}',
+);
+```
+
+The chart fills its constraints. When the height is unbounded, it uses
+`defaultHeight`.
+
+## Buckets
+
+| Field | Description |
+| --- | --- |
+| `time` | When the interval began; columns are evenly spaced in the order given |
+| `inputTokens` | Prompt tokens processed |
+| `outputTokens` | Tokens generated |
+| `cachedTokens` | Prompt tokens served from a cache — counted **apart** from `inputTokens`, not inside it |
+| `cost` | What the interval cost; null draws no point |
+
+A value that is not finite, or negative, counts as zero. `total` is the sum of
+the three kinds and `cacheHitRate` is cached over the whole prompt.
+
+## Numbers
+
+| Function | Description |
+| --- | --- |
+| `usageTotals(buckets)` | `input`, `output`, `cached`, `tokens`, `cost` and `cacheHitRate` over all of them |
+| `compactCount(value)` | `950`, `12.4k`, `3.1M`, `2B` — the default axis format |
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `showCost`, `costColor`, `costFormatter` | The cost line and its right-hand axis; omitted when no bucket has a cost |
+| `inputColor`, `outputColor`, `cachedColor` | The stack |
+| `barSpacing`, `barRadius` | Column gap and the rounding of the top |
+| `tokenFormatter`, `timeFormatter`, `axisLabelStyle`, `gridColor` | Axes |
+| `showLegend`, `legendStyle` | The series, in the corner |
+
+## Touch
+
+`onTouch` reports a `UsageTouchDetails` with the bucket's `index` and `bucket`,
+and `null` when the pointer leaves. `tooltipBuilder` builds a card beside the
+column.
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/training-curve-chart.md b/doc/training-curve-chart.md
new file mode 100644
index 0000000..65f09b6
--- /dev/null
+++ b/doc/training-curve-chart.md
@@ -0,0 +1,79 @@
+# Training curves
+
+
+
+`TrainingCurveChart` draws the loss and accuracy curves of one or more training
+runs, the way a training dashboard does: raw readings faint under a **smoothed**
+line, an optional **log axis** for a loss that spans decades, the **best
+checkpoint** of each run marked, and the step a run's loss **diverged** at.
+
+```dart
+TrainingCurveChart(
+ runs: [
+ TrainingRun(label: 'train', points: train),
+ TrainingRun(label: 'val', points: val, dashed: true),
+ ],
+ smoothing: 0.9,
+ logY: true,
+ gapBetween: (0, 1), // shade the train/validation gap
+);
+```
+
+The chart fills its constraints. When the height is unbounded, it uses
+`defaultHeight`.
+
+## Runs
+
+| Type | Fields |
+| --- | --- |
+| `TrainingPoint` | `step` (optimiser step, epoch or tokens seen), `value` |
+| `TrainingRun` | `label`, `points`, `color`, `dashed`, `data` |
+
+A point whose value is not finite leaves a gap in the line; a run of one point,
+or of none, draws nothing and does not throw.
+
+## Smoothing
+
+`smoothing` runs from 0 (the raw line) to just under 1. It is the exponential
+moving average dashboards use, corrected for its slow start, so the first
+readings are not pulled toward zero. With `showRaw` the unsmoothed readings stay
+as a faint line at `rawOpacity`.
+
+## What it marks
+
+| Mark | Meaning | Switch |
+| --- | --- | --- |
+| Ringed dot | A run's best checkpoint: its lowest loss, or its highest value when `lowerIsBetter` is false | `showBest` |
+| Red line, "diverged" | The step the loss climbed past `divergenceFactor` times its lowest, or went NaN | `showDivergence` |
+| Shaded band | The gap between two runs, usually train and validation — overfitting shows as the band opening | `gapBetween: (train, val)` |
+
+## Numbers
+
+| Function | Description |
+| --- | --- |
+| `smoothValues(values, weight)` | The smoothed series; null where a value was not finite |
+| `bestIndex(values, lowerIsBetter:)` | The best reading's index |
+| `divergenceIndex(values, factor:)` | Where a loss blew up, or `null` |
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `logY` | A logarithmic value axis; readings of zero or below are not drawn |
+| `lineWidth`, `palette` | Line weight and the colours runs take in turn |
+| `showLegend`, `legendStyle` | Run names in the corner when there is more than one |
+| `showAxes`, `stepFormatter`, `valueFormatter`, `xAxisTitle`, `yAxisTitle` | Axes |
+| `gridColor`, `crosshairColor`, `bestColor`, `divergenceColor`, `gapColor` | Colours |
+
+## Touch
+
+`onTouch` reports a `TrainingTouchDetails` with the `step` and a `TrainingReading`
+per run — its nearest `point` and `smoothed` value — and `null` when the pointer
+leaves. `tooltipBuilder` builds a card beside the crosshair.
+
+## Animation
+
+`animationDuration` draws the lines in from the left. It runs again only when
+the runs' values, `smoothing` or `logY` change.
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/training-timeline-chart.md b/doc/training-timeline-chart.md
new file mode 100644
index 0000000..842a352
--- /dev/null
+++ b/doc/training-timeline-chart.md
@@ -0,0 +1,67 @@
+# Training timeline
+
+
+
+`TrainingTimelineChart` shows training jobs on a timeline: a lane per machine or
+pool, a bar from start to end **coloured by how the job finished**, and a strip
+underneath counting how many jobs were running at each moment. It answers "what
+was the cluster doing, and where did it fall over?"
+
+```dart
+TrainingTimelineChart(
+ jobs: [
+ TrainingJob(
+ name: 'llama-8b-sft',
+ node: 'pod-a',
+ start: DateTime(2026, 9, 1, 8),
+ end: DateTime(2026, 9, 1, 19),
+ status: JobStatus.completed,
+ gpus: 64,
+ ),
+ TrainingJob(name: 'rl-sweep', node: 'pod-b', start: DateTime(2026, 9, 1, 10)),
+ ],
+);
+```
+
+The chart fills its constraints. When the height is unbounded, it uses
+`defaultHeight`. It is a `TradeTimelineChart` underneath, so its lanes, time
+axis and pointer behave as that chart's do.
+
+## Jobs
+
+| Field | Description |
+| --- | --- |
+| `name` | What the job is called |
+| `start`, `end` | When it ran; a null `end`, or `JobStatus.running`, runs to `now` |
+| `node` | The lane: a machine or a pool; null is an unnamed lane |
+| `status` | `running`, `completed`, `failed`, `preempted` or `cancelled` |
+| `gpus`, `data` | Accelerators held, and app data returned on touch |
+
+## Colour
+
+| Status | Colour parameter |
+| --- | --- |
+| `running` | `runningColor` |
+| `completed` | `completedColor` |
+| `failed` | `failedColor` |
+| `preempted` | `preemptedColor` |
+| `cancelled` | `cancelledColor` |
+
+`colorOf(status)` returns the colour in use, for a legend of your own.
+
+## Touch
+
+`onTouch` reports a `TrainingJobTouchDetails` with the `job`, the `time` under
+the pointer and `duration(now)`, and `null` when the pointer leaves.
+`tooltipBuilder` builds a card beside the bar.
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `showRunningCount`, `countColor` | The strip counting concurrent jobs |
+| `laneLabelWidth`, `laneLabelStyle` | The lane names |
+| `axisLabelStyle`, `timeFormatter`, `gridColor` | The time axis |
+| `now` | The time running jobs are drawn to |
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/var-chart.md b/doc/var-chart.md
new file mode 100644
index 0000000..73bba84
--- /dev/null
+++ b/doc/var-chart.md
@@ -0,0 +1,49 @@
+# Value at risk
+
+
+
+`VarChart` shows the shape of a set of returns with the loss tail picked out and
+two figures marked: **value at risk** (VaR), the return that only a small share
+of outcomes were worse than, and **expected shortfall** (CVaR), the average of
+the outcomes beyond it. Both are worked out from the history itself.
+
+```dart
+VarChart(returns: dailyReturns, confidence: 0.99);
+```
+
+Returns are fractions: `-0.03` is a 3% loss. The chart fills its constraints.
+When the height is unbounded, it uses `defaultHeight`; a box too short for the
+row of figures shows only the histogram.
+
+## The numbers
+
+`ValueAtRisk.fromReturns(returns, confidence: 0.95)` returns:
+
+| Field | Description |
+| --- | --- |
+| `valueAtRisk` | The return only `1 - confidence` of outcomes fell below; zero or less for a history with losses |
+| `expectedShortfall` | The average of the outcomes at or beyond `valueAtRisk`; never above it |
+| `mean`, `standardDeviation` | Average, and the sample standard deviation |
+| `worst`, `count` | The worst return, and how many there were |
+
+It uses the historical method — no assumption about the shape of returns — with
+linear interpolation between the two outcomes the threshold falls between.
+Returns that are not finite are skipped.
+
+`varBins(returns, valueAtRisk:, tailColor:)` counts the returns into
+`HistogramBin`s and colours those in the tail, if you want to hand them to a
+`HistogramChart` of your own.
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| `confidence` | The share of outcomes VaR is not worse than; 0.95 by default |
+| `binCount`, `binWidth` | How the histogram is cut; the default is the square root of the count |
+| `barColor`, `tailColor` | Bars outside and inside the loss tail |
+| `showVarLine`, `showShortfallLine`, `showMeanLine` | Which lines mark the figures |
+| `showStats`, `statsBuilder` | The row of figures, and a builder for your own |
+| `valueFormatter` | Writes a return; the default writes a percentage |
+| `onTouch`, `tooltipBuilder` | The histogram's touch and card |
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/doc/volatility-surface-chart.md b/doc/volatility-surface-chart.md
new file mode 100644
index 0000000..4f80ad5
--- /dev/null
+++ b/doc/volatility-surface-chart.md
@@ -0,0 +1,68 @@
+# Volatility surface
+
+
+
+`VolatilitySurfaceChart` draws implied volatility across strike and expiry at
+once, as a heatmap. `VolatilityCurveChart` shows one smile or one term structure
+at a time; the surface is the whole picture, where a skew that steepens into
+short expiries or a kink at one strike stands out as colour.
+
+```dart
+VolatilitySurfaceChart(
+ strikes: const [90, 95, 100, 105, 110],
+ expiries: const ['1W', '1M', '3M', '6M'],
+ volatilities: [
+ [0.34, 0.30, 0.28, 0.29, 0.32], // one row per expiry
+ [0.31, 0.28, 0.26, 0.27, 0.29],
+ [0.29, 0.27, 0.25, 0.26, 0.28],
+ [0.28, 0.26, 0.25, 0.26, 0.27],
+ ],
+ spot: 100,
+);
+```
+
+The chart fills its constraints. When the height is unbounded, it uses
+`defaultHeight`. It is built on `HeatmapChart`, so a cell is `null` where there
+is no quote and is left empty.
+
+## Data
+
+| Parameter | Description |
+| --- | --- |
+| `strikes` | One per column, left to right |
+| `expiries` | One name per row, top to bottom |
+| `volatilities` | A row per expiry holding a value per strike, as fractions: 0.25 is 25% |
+| `spot` | The underlying's price; used to find the at-the-money strike for the skew |
+
+## Colour
+
+`lowColor`, `midColor` and `highColor` run the scale, cool to warm by default.
+`minVolatility` and `maxVolatility` fix its ends — useful to keep two surfaces
+comparable — and otherwise take the lowest and highest reading drawn.
+
+## Numbers
+
+| Function | Description |
+| --- | --- |
+| `atTheMoneyIndex(strikes, spot)` | The column of the strike nearest the spot |
+| `surfaceSkew(row, atmIndex)` | Each strike's volatility less the at-the-money one |
+
+## Touch
+
+`onTouch` reports a `VolatilitySurfaceTouchDetails` with the `expiry`, `strike`,
+`volatility`, the `atTheMoneyVolatility` of the same expiry and the `skew`
+between them, and `null` when the pointer leaves. `tooltipBuilder` builds a card
+beside the square.
+
+## Appearance
+
+| Parameter | Description |
+| --- | --- |
+| `showValues`, `valueFormatter`, `labelStyle` | Volatilities written in the squares |
+| `strikeFormatter`, `axisLabelStyle` | Strike labels and their style |
+| `expiryAxisWidth`, `strikeAxisHeight` | Room for the labels |
+| `spacing`, `radius` | Gap between squares and their corner rounding |
+| `animationDuration`, `animationCurve`, `animateOnMount` | Fade-in |
+| `backgroundColor`, `padding`, `defaultHeight` | Box |
+
+[← All docs](README.md) · [Package README](../README.md)
diff --git a/example/README.md b/example/README.md
index 5ff897d..81dfdc7 100644
--- a/example/README.md
+++ b/example/README.md
@@ -96,7 +96,7 @@ All nine follow the palette switch in the app bar.
## The Gallery tab
Every chart in the package that is not the candlestick, depth or series screen
-— 34 of them — with a page each: the order-flow and derivatives charts, the
+— 50 of them — with a page each: the order-flow and derivatives charts, the
ones a backtest report is built from, and the ones a dashboard is.
The tab opens on a searchable list grouped by what the charts are for. Tapping
diff --git a/example/lib/src/gallery/gallery_data.dart b/example/lib/src/gallery/gallery_data.dart
index ccfc83c..4625407 100644
--- a/example/lib/src/gallery/gallery_data.dart
+++ b/example/lib/src/gallery/gallery_data.dart
@@ -371,3 +371,469 @@ List
+
