chart-scrub-readout — Claude Code rule: what it does, how to install
chart-scrub-readout — a Claude rule that turns a chart already on screen into something you can scrub: a tracking line, a marker on the polyline, and a tooltip reading out date and value.
MIT ★ 328 updated 2026-10-29
.claude/rules/chart-scrub-readout.mdWhat chart-scrub-readout does
This rule is for scenes where the chart is already drawn. It adds a read head on top: a vertical line follows the scrub position, a marker dot rides the baked polyline, and a tooltip prints date: value for the current point. The series is baked once into a literal DATA array of { d, v } entries, and the polyline's points attribute comes out of it through plain mapping functions.
Everything hangs off a single driver tween from p: 0 → 1. Its onUpdate projects the line x, the marker coordinates and the tooltip transform, so any seek lands the same frame. Only the text is stepped: the nearest data index is guarded, and textContent is rewritten when that index changes rather than every frame. A second series can light up at the cross, and the scrub can decelerate onto the peak.
Two things break it. Give the tooltip a fixed min-width and font-variant-numeric: tabular-nums, otherwise the box resizes as digits change. Size the SVG so viewBox units equal CSS pixels, because the line, marker and HTML tooltip then share one coordinate space. The rule never draws the chart in; it assumes the graphic exists and only moves the read head across it.
What it helps with
- scrub an already-rendered chart with a tracking line and marker
- derive line, marker and tooltip from one driver tween
- step the date/value readout per data point instead of per frame
- light up a second series when the playhead crosses it
- ease the scrub onto the peak and pop the marker at landing
Example prompts for the agent
- Apply
chart-scrub-readoutto this chart: tracking line, marker on the polyline, and a date/value tooltip fed from aDATAarray. - Drive the scrub from one tween
p: 0 → 1and rewrite the tooltip text only when the nearest index changes. - Use the peak-stop variation so the scrub slows onto the last point and the marker pops on landing.
How to install chart-scrub-readout
Manually: put the files in place
.claude/rules/chart-scrub-readout.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/chart-scrub-readout.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/chart-scrub-readout.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/chart-scrub-readout.mdManually: put the files in place
.clinerules/chart-scrub-readout.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about chart-scrub-readout
How to install chart-scrub-readout in Claude Code?
Add the rule as a file at .claude/rules/chart-scrub-readout.md in the project.
What does chart-scrub-readout do?
It puts a scrub readout on a chart that is already rendered: a tracking line, a marker on the polyline, and a date/value tooltip, all derived from one tween.
Does it draw the chart itself?
No. It expects the graphic to exist and only moves a read head across it. Arrival animations belong to the neighbouring rules it points at.
Source text
chart-scrub-readout.md · MIT
---
name: chart-scrub-readout
description: A cursor/playhead scrubs an already-drawn chart — one driver moves a vertical tracking line and marker along a baked data polyline while a date/value tooltip steps through the data array; a second series can activate on cross. Deterministic data, readout writes only on index change.
metadata:
tags: chart, scrub, readout, tooltip, tracking-line, data, cursor, playhead
---
# Chart Scrub Readout
The chart is already ON screen — this rule **interrogates** it. A vertical tracking line rides the scrub position, a marker dot follows the series, and a live tooltip reads out `date: value` per position, values flickering past like an odometer. It's the "this data is real — look closer" beat: the scrub proves the chart is an instrument, not a picture.
Boundary with its neighbors: [stat-bars-and-fills.md](stat-bars-and-fills.md) owns the chart's ARRIVAL; [counting-dynamic-scale.md](counting-dynamic-scale.md) owns a single number swelling in place. This rule assumes the graphic already exists and adds a **read head** moving across it. The three chain naturally: the line draws in (svg-path-draw / stat-bars), this rule scrubs it, and the landing value hands off to a count-up lockup.
## How It Works
1. **Data baked at setup** — a literal `DATA` array of `{ d, v }` points (or a pure index formula). The polyline's `points` attribute is computed ONCE from `DATA` by pure mapping functions: chart and readout share one source of truth. The argument of the shot is "this data is real" — a random walk regenerated per render breaks both determinism and the rhetorical claim.
2. **One driver tween** `p: 0 → 1` derives everything in its `onUpdate`: tracking-line x, marker x/y, tooltip position. Every output is a pure function of `p` — any seek lands the identical frame. Parallel tweens that merely share timing drift apart under rounding and read as chart chrome, not a read head.
3. **The marker rides the polyline** — its y interpolates between the two neighboring baked points, from the same arrays that built the chart; a separately-keyframed marker inevitably floats off the line.
4. **The readout is threshold-stepped** — the nearest data index derives from `p`, and `textContent` is written ONLY when that index changes (last-index guard). Transforms glide per frame (compositor-cheap); text steps per data point — no per-frame DOM text thrash. The guard is an optimization, not state: any seek recomputes the same index and the same text.
## Recipe
```html
<!-- inside a standard scene clip. Size the SVG so viewBox units === CSS pixels:
one coordinate space serves the polyline, tracking line, marker, AND the HTML tooltip. -->
<div class="chart-wrap">
<!-- position: relative — the tooltip transforms against this box -->
<svg class="chart" viewBox="0 0 CHART_W CHART_H" width="CHART_W" height="CHART_H">
<polyline id="series-a" class="series" fill="none" />
<line id="track-line" y1="0" y2="CHART_H" stroke-dasharray="6 6" />
<circle id="marker" r="MARKER_R" />
</svg>
<div class="tooltip" id="tooltip">
<span id="tip-date">{firstDate}</span>
<span id="tip-value">{firstValue}</span>
</div>
</div>
```
```css
.tooltip {
position: absolute;
top: 0;
left: 0;
min-width: TIP_MIN_WIDTH; /* fixed — the box must not resize as values change length */
}
#tip-value {
font-variant-numeric: tabular-nums; /* MANDATORY — digits flicker past; widths must not */
}
```
```js
// Data baked at setup — literal values.
const DATA = [
{ d: "{date1}", v: V1 },
// ... N points, chronological ...
];
// Pure mapping functions — geometry derives from DATA once.
const PAD = CHART_PAD;
const PLOT_W = CHART_W - PAD * 2;
const PLOT_H = CHART_H - PAD * 2;
const vals = DATA.map((p) => p.v);
const V_MIN = Math.min(...vals);
const V_MAX = Math.max(...vals);
const X = (i) => PAD + (i / (DATA.length - 1)) * PLOT_W;
const Y = (v) => PAD + PLOT_H * (1 - (v - V_MIN) / (V_MAX - V_MIN));
document
.getElementById("series-a")
.setAttribute("points", DATA.map((p, i) => `${X(i)},${Y(p.v)}`).join(" "));
const line = document.getElementById("track-line");
const marker = document.getElementById("marker");
const tooltip = document.getElementById("tooltip");
const tipDate = document.getElementById("tip-date");
const tipValue = document.getElementById("tip-value");
// Tooltip pops in as the scrub begins — a small fromTo scale/opacity spring at SCRUB_AT.
// ONE driver — line, marker, and tooltip are all projections of p.
const scrub = { p: 0 };
let lastIdx = -1;
tl.to(
scrub,
{
p: 1,
duration: SCRUB_DUR,
ease: SCRUB_EASE,
onUpdate: () => {
const f = scrub.p * (DATA.length - 1); // fractional index
const i = Math.min(DATA.length - 2, Math.floor(f));
const t = f - i;
const x = X(i) + (X(i + 1) - X(i)) * t;
const y = Y(DATA[i].v) + (Y(DATA[i + 1].v) - Y(DATA[i].v)) * t;
// Transforms glide every frame (cheap, deterministic)
line.setAttribute("x1", x);
line.setAttribute("x2", x);
marker.setAttribute("cx", x);
marker.setAttribute("cy", y);
tooltip.style.transform = `translate(${x + TIP_DX}px, ${y - TIP_DY}px)`;
// Text steps only when the nearest data point changes
const idx = Math.round(f);
if (idx !== lastIdx) {
tipDate.textContent = DATA[idx].d;
tipValue.textContent = `${DATA[idx].v.toLocaleString()} {unitLabel}`;
lastIdx = idx;
}
},
},
SCRUB_AT,
);
// End hold: the driver finishes before the scene does — the landed value reads.
```
## Variations
- **Peak stop** — the scrub is the wind-up, the landing is the stat: `SCRUB_EASE: "power3.out"` decelerates onto the final/peak point, then pop the emphasis at landing (`fromTo` marker `scale: 1 → PEAK_POP_SCALE` at `SCRUB_AT + SCRUB_DUR`). Pair with a pill tooltip that springs to its final label ([spring-pop-entrance.md](spring-pop-entrance.md)) — the classic "line breaks above the band" climax.
- **Second-series activation on cross** — series B sits dimmed; at `SCRUB_AT + SCRUB_DUR * CROSS_P` tween its stroke to the lit color (0.25s, `power2.out`), and in the driver's `onUpdate` read from B's array once `scrub.p ≥ CROSS_P` (still index-guarded). The color flip lands ON the cross — same-frame causality.
- **Two-chart glide** — two scrub beats: sweep chart A, glide the cursor/tooltip group across the gutter (a plain `x` tween, no readout — dead travel, not data), then chart B activates with its own driver. One driver per chart.
- **Cursor-led scrub** — an oversized cursor is the visible actor: another projection of the SAME driver (positioned from `x` in the same `onUpdate`, tip at the tracking line's head) — never a second tween that merely matches timing. Cursor look and click grammar from [cursor-click-ripple.md](cursor-click-ripple.md).
- **Playhead form** — no cursor; the tracking line IS the actor (timeline scrubbers, audio waves, session replays). `ease: "none"` — mechanical playback, not a hand.
## Values
| token | range / default | notes |
| ----------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| N (data points) | 10–40 | <10 reads as a slideshow; >40 blurs into texture. The flicker is the point — only first and final values must be legible |
| SCRUB_DUR | 1.5–3s | shorter = confident sweep; longer = inspection. Leave ≥0.8s of scene after the driver ends so the landed value holds |
| SCRUB_EASE | `power1.inOut` default | `"none"` playhead form; `power3.out` peak stop. Never `back.out` — a read head that overshoots and re-reads looks broken |
| CROSS_P | 0.55–0.75 | earlier and A never establishes; later and B's readout has no time to live |
| TIP_DX / TIP_DY | 16–48px, up-and-right | flip the sign near the chart's right edge so the tooltip never exits the frame |
| MARKER_R / stroke width | r 6–12 / 4–8px | the marker must dominate the line it rides |
| TIP_MIN_WIDTH | ≥ longest `date: value` state | without it the box breathes as digits change |
## Critical Constraints
- **`DATA` is literal at setup**; polyline points derive from it via pure functions — chart and readout share one source of truth.
- **Seed at setup** — call the scrub applier once with `p = 0` right after building (à la `3d-camera-flight`'s `applyCamera()`), or a seek to t=0 before the driver runs shows the tracking line/marker at their HTML-default positions.
- **Single driver** — one `p` tween; all scrub outputs (line, marker, tooltip, any cursor) computed in its `onUpdate`, each a pure function of `p`.
- **Readout writes guarded by index change** — `onUpdate` stays O(1): a few attribute sets, one transform, text only on step.
- **SVG `viewBox` units = CSS pixels** (`viewBox="0 0 W H"` with matching `width`/`height`) — one coordinate space must serve the SVG internals and the HTML tooltip's transform.
- **`tabular-nums` + fixed `min-width`** on the tooltip value.
- **The chart pre-exists** — draw-in belongs to `svg-path-draw` / `stat-bars-and-fills`; sequence it BEFORE the scrub, don't blend them.
- **Land the read** — hold the final value ≥0.8s (or hand off to a count-up lockup).
## See also
`svg-path-draw` (the series draws in first) · `stat-bars-and-fills` (surrounding dashboard chrome) · `spring-pop-entrance` (peak dot + pill pop at the landing) · `counting-dynamic-scale` (closing stat lockup) · `cursor-click-ripple` / `context-sensitive-cursor` (the cursor-led form's actor) · `control-target-sync` (the sibling WRITE direction — there a control edits a target; here a scrub reads a dataset).
© coco-research · MIT · coco-research/coco