# Trace-chart viewer comfort (Tier 1) — ordinal x-axis + zoom/pan/cursor-sync — Design Spec

**Date:** 2026-06-19
**Status:** Draft — awaiting user spec review
**Authors:** orchestrator + Claude

Seeds: Gitea #103 (reference issue; derived-fork decision log in its comments).
Lineage: #101 (trace charts, first cut), C22 (playground = trace explorer), C14
(engine headless — the viewer is a downstream read of recorded traces).

## Goal

Make the served trace chart *feel* like a chart rather than a screenshot, and satisfy
the one explicitly-requested data-model change: **the x-axis must not be continuous by
default** (gaps for non-trading time collapse), with a continuous spacing available as a
one-click option.

Two strands, both confined to the read/render side:

1. **Ordinal x-axis (default) + in-page continuous toggle.** Plot every slot at an even
   ordinal position so nights/weekends collapse; one toggle flips to true
   timestamp-proportional (continuous) spacing and back.
2. **Tier-1 interaction comfort.** wheel-zoom + drag-pan + double-click-reset on the
   x-axis; a value readout at the cursor (the real timestamp in ordinal mode); the
   crosshair synchronized across stacked panels.

Non-goals (explicitly deferred, named so the cut stays honest): epoch→date axis labels /
session-aware ticks (needs instrument context — #102 / Tier-3); a live `aura serve`
backend (the page stays static & self-contained); LOD / downsampling ("mipmapping");
families/comparison meta-views (C21); drawing tools (C22 forbids a scene editor).

## Feature-acceptance criterion (applied prospectively)

aura's criterion (CLAUDE.md domain invariants + the skills default): the intended
audience reaches for it, it improves legibility/correctness, and it reintroduces no
failure class a core constraint forbids.

- **Audience reaches for it.** A trader reading a recorded backtest trace expects bars
  evenly spaced (no weekend chasms) and expects to wheel-zoom / drag-pan — every charting
  tool behaves so. The worked invocation (below) is unchanged; what changes is that the
  emitted page is legible at a glance.
- **Improves legibility, not just decoration.** Gap-collapse is the difference between a
  trace dominated by blank overnight stretches and one where the signal fills the width —
  directly serving C22's "trace explorer" mission.
- **Reintroduces no forbidden failure class.** This is a pure read-side render concern.
  The engine, the recorded SoA traces (C7), `build_chart_data`'s union-spine alignment,
  and the `ColumnarTrace`/`TraceStore` contract are all untouched (C14: engine knows no
  UI). Determinism/causality (C1/C2) live in the engine, not the viewer.

## Architecture

The whole feature lives in two files; the Rust serve contract is unchanged.

- `crates/aura-cli/assets/chart-viewer.js` — the pure `buildCharts` gains an `xMode`
  parameter and assembles ordinal-vs-continuous uPlot configs + the interaction plugin +
  the panel cursor-sync key; the browser-only `mount` gains a re-render-on-toggle loop.
- `crates/aura-cli/src/render.rs` — `CHART_HEAD` gains the toggle control; a small
  chart-only `<style>` is injected for it and for legend/readout polish.

Unchanged (asserted, not re-derived): `build_chart_data` (`main.rs`) still emits
`ChartData { xs, series }`; `render_chart_html` still injects `window.AURA_TRACES =
{ mode, xs, series }`; `xs` is the real union-spine timestamps and `series[*].points` are
`Option<f64>` over `xs` with `null` gaps verbatim. The viewer never needs more data than
it already receives — the ordinal indices are derived client-side from `xs.length`, and
the real timestamp for any slot is read back from the injected `xs`.

### Why client-side, default ordinal (derived fork, recorded on #103)

An **in-page toggle** beats a CLI flag: it lets the viewer compare both spacings without
regenerating the page, and keeps the injected payload + the entire Rust side untouched
(no repeat of the #102 manifest-drift). **Ordinal is the default** (the issue's primary
clause "should not be continuous"); continuous is the "(or only optional)" fallback, one
click away. Full rationale + the three secondary derived forks (interaction gestures,
ordinal label = raw `xs[i]`, global toggle, panel-only sync) are minuted in #103's
comments.

## Concrete code shapes

### 1. Worked user-facing surface (the acceptance evidence)

The CLI invocation is **unchanged** — the comfort is in the emitted page:

```console
$ aura run --trace demo            # persist taps (unchanged)
$ aura chart demo > demo.html      # overlay, self-contained (unchanged invocation)
$ aura chart demo --panels > demo_panels.html
```

Opening `demo.html` now:

- the x-axis is **ordinal by default** — every recorded slot is evenly spaced, so an
  overnight/weekend gap in `xs` no longer leaves a horizontal blank; the trace fills the
  width.
- a header control reads **`x: collapsed (gaps off)`**; clicking it flips to
  **`x: continuous (real time)`** and re-renders both/all charts in that spacing; clicking
  again flips back. (Label text is illustrative; exact wording is the planner's.)
- **wheel** over the plot zooms the x-axis around the cursor; **drag** pans; **double-click**
  restores the full range.
- the uPlot **legend** reads out each series' value at the cursor; in ordinal mode its
  x-readout shows the **real `xs[i]` timestamp** for the hovered slot (not the ordinal
  index).
- in `--panels`, the vertical crosshair is **synchronized** — hovering one panel lines the
  cursor up across all panels at the same slot.

### 2. `buildCharts` — before → after (the load-bearing change)

Before (today — implicit continuous, x = real `xs`):

```js
// buildCharts(traces, mode) -> configs; data[0] is always traces.xs
function buildCharts(traces, mode) {
  var xs = traces.xs;
  var series = traces.series;
  if (mode === "panels") {
    return series.map(function (s, i) {
      return { opts: { title: s.name, scales: { x: { time: false }, [s.y_scale_id]: {} },
                       series: [{}, { label: s.name, scale: s.y_scale_id, stroke: ... }],
                       axes: [{}, { scale: s.y_scale_id }] },
               data: [xs, s.points] };
    });
  }
  // overlay …
  return [{ opts: { scales, series: uSeries, axes }, data: [xs].concat(series.map(s => s.points)) }];
}
```

After (x-mode parameter; ordinal default; interaction plugin + panel sync):

```js
// buildCharts(traces, mode, xMode) -> configs.  xMode in {"ordinal","continuous"},
// default "ordinal".  In ordinal mode data[0] is the index spine [0..n-1] and the
// x-axis/legend map an index back to the real traces.xs[i]; in continuous mode data[0]
// is traces.xs (today's behaviour).  series points (data[1..]) are untouched in either
// mode — null gaps preserved verbatim.
function buildCharts(traces, mode, xMode) {
  xMode = xMode || "ordinal";
  var xs = traces.xs;
  var n = xs.length;
  var idx = []; for (var i = 0; i < n; i++) idx.push(i);   // the ordinal spine
  var ordinal = xMode !== "continuous";
  var xData = ordinal ? idx : xs;

  // map an x-position to its real-timestamp label string (total, no epoch assumption):
  //   ordinal  -> position is an index -> xs[round(pos)]
  //   continuous -> position already IS the timestamp
  function xLabel(pos) {
    if (!ordinal) return String(pos);
    var k = Math.max(0, Math.min(n - 1, Math.round(pos)));
    return String(xs[k]);
  }
  var xAxis = ordinal ? { values: function (u, splits) { return splits.map(xLabel); } } : {};
  var xSeries = { value: function (u, v) { return v == null ? "--" : xLabel(v); } };

  var plugins = [wheelZoomPlugin()];          // pure factory; hooks run only in browser
  var cursor  = { drag: { x: false, y: false } };   // drag-box-zoom off; we pan instead

  if (mode === "panels") {
    var SYNC = "aura-x";                       // shared key -> crosshair sync across panels
    return traces.series.map(function (s, i) {
      return {
        opts: {
          title: s.name,
          scales: { x: { time: false }, [s.y_scale_id]: {} },
          series: [xSeries, { label: s.name, scale: s.y_scale_id, stroke: PALETTE[i % PALETTE.length] }],
          axes: [xAxis, { scale: s.y_scale_id }],
          cursor: Object.assign({ sync: { key: SYNC } }, cursor),
          plugins: plugins,
        },
        data: [xData, s.points],
      };
    });
  }

  // overlay: one chart, all series, each own y-scale; same xData spine.
  var scales = { x: { time: false } };
  var uSeries = [xSeries];
  var axes = [xAxis];
  traces.series.forEach(function (s, i) {
    scales[s.y_scale_id] = {};
    uSeries.push({ label: s.name, scale: s.y_scale_id, stroke: PALETTE[i % PALETTE.length] });
    if (i < 2) axes.push({ scale: s.y_scale_id, side: i === 0 ? 3 : 1 });
  });
  return [{
    opts: { scales: scales, series: uSeries, axes: axes, cursor: cursor, plugins: plugins },
    data: [xData].concat(traces.series.map(function (s) { return s.points; })),
  }];
}
```

### 3. `wheelZoomPlugin` — new (browser-only hooks, pure factory)

A small uPlot plugin: on `init` it attaches wheel-zoom + pointer-drag-pan to `u.over` and
a double-click reset. The factory is pure (returns a `{ hooks: { init } }` object — safe
to construct under the headless node guard); the hook body only runs in a browser.

```js
function wheelZoomPlugin() {
  var ZOOM = 0.9;   // wheel notch shrinks/grows the visible x-range by this factor
  return { hooks: { init: function (u) {
    var over = u.over;
    over.addEventListener("wheel", function (e) {
      e.preventDefault();
      var rect = over.getBoundingClientRect();
      var xVal = u.posToVal(e.clientX - rect.left, "x");
      var lo = u.scales.x.min, hi = u.scales.x.max;
      var f = e.deltaY < 0 ? ZOOM : 1 / ZOOM;            // up = zoom in
      u.setScale("x", { min: xVal - (xVal - lo) * f, max: xVal + (hi - xVal) * f });
    }, { passive: false });
    // drag-pan
    over.addEventListener("mousedown", function (d) {
      if (d.button !== 0) return;
      var x0 = d.clientX, lo = u.scales.x.min, hi = u.scales.x.max;
      var unitsPerPx = (hi - lo) / over.clientWidth;
      function move(m) { var dx = (m.clientX - x0) * unitsPerPx;
        u.setScale("x", { min: lo - dx, max: hi - dx }); }
      function up() { document.removeEventListener("mousemove", move);
        document.removeEventListener("mouseup", up); }
      document.addEventListener("mousemove", move);
      document.addEventListener("mouseup", up);
    });
    over.addEventListener("dblclick", function () {          // reset to full range
      u.setScale("x", { min: u.data[0][0], max: u.data[0][u.data[0].length - 1] });
    });
  } } };
}
```

### 4. `mount` — before → after (re-render on toggle)

Before: one pass, instantiate each config. After: a `render(xMode)` that tears down and
rebuilds, wired to the header toggle; default `xMode = "ordinal"`.

```js
function mount() {
  var traces = window.AURA_TRACES;
  var stage = document.getElementById("stage");
  var toggle = document.getElementById("xmode-toggle");
  var xMode = "ordinal";
  var insts = [];
  function render() {
    insts.forEach(function (u) { u.destroy(); }); insts = [];
    stage.innerHTML = "";
    var configs = buildCharts(traces, traces.mode, xMode);
    var w = stage.clientWidth || 900;
    var h = configs.length > 1 ? Math.max(160, Math.floor(440 / configs.length)) : 460;
    configs.forEach(function (cfg) {
      insts.push(new uPlot(Object.assign({ width: w, height: h }, cfg.opts), cfg.data, stage));
    });
    if (toggle) toggle.textContent = xMode === "ordinal" ? "x: collapsed (gaps off)" : "x: continuous (real time)";
  }
  if (toggle) toggle.addEventListener("click", function () {
    xMode = xMode === "ordinal" ? "continuous" : "ordinal"; render();
  });
  render();
}
```

### 5. `render.rs` `CHART_HEAD` — before → after

Add the toggle control to the chart header (graph page unaffected — it has its own
`GRAPH_HEAD`), plus a tiny chart-only `<style>` injected in `render_chart_html` after the
uPlot CSS.

```rust
// before
const CHART_HEAD: &str = r#"<header>
  <b>aura chart</b>
  <span class="sub">timestamp-aligned trace series</span>
</header>
<div id="stage"></div>
<pre id="err"></pre>
"#;

// after — a toggle button the viewer wires up; default label set by mount()
const CHART_HEAD: &str = r#"<header>
  <b>aura chart</b>
  <span class="sub">timestamp-aligned trace series</span>
  <button id="xmode-toggle" type="button">x: collapsed (gaps off)</button>
</header>
<div id="stage"></div>
<pre id="err"></pre>
"#;
```

The injected chart-only style (small; lives in `render_chart_html`, not the shared
`SHELL_HEAD`): a button rule (`#xmode-toggle { … cursor:pointer; … }`) consistent with the
dark palette. Exact bytes are the planner's.

## Components

| Component | File | Change |
|---|---|---|
| `buildCharts` | chart-viewer.js | gains `xMode` (default `"ordinal"`); ordinal index spine + x label/legend mapping; attaches `wheelZoomPlugin` + (panels) `cursor.sync` |
| `wheelZoomPlugin` | chart-viewer.js | new pure factory; browser-only wheel-zoom / drag-pan / dblclick-reset hooks |
| `mount` | chart-viewer.js | `render(xMode)` teardown+rebuild; toggle wiring; default ordinal |
| `CHART_HEAD` + chart `<style>` | render.rs | toggle button + its styling |
| node guards | tests/*.mjs + .rs | new xmode guard; existing build/gap guards updated for the ordinal default |

## Data flow

Unchanged through Rust: drained taps → `ColumnarTrace` → `TraceStore` →
`build_chart_data` (union-spine `join_on_ts`) → `ChartData { xs, series }` →
`render_chart_html` → `window.AURA_TRACES = { mode, xs, series }`.

New, client-side only: `mount` → `buildCharts(traces, mode, xMode)`:
- `xData = xMode==="ordinal" ? [0..n-1] : xs` becomes `data[0]`.
- `series[*].points` become `data[1..]` **verbatim** (null gaps preserved — unchanged).
- the x-axis tick `values` and the x-series legend `value` map a position back to
  `xs[round(pos)]` (ordinal) or show it directly (continuous).
- panels carry a shared `cursor.sync.key`; the plugin's hooks drive zoom/pan/reset.

## Error handling

No new error surface. `buildCharts` with an unrecognized `xMode` falls back to ordinal
(`xMode !== "continuous"` ⇒ ordinal) — total, never throws. An empty trace (`xs.length
=== 0`) yields an empty index spine and empty data arrays, exactly as today. The Rust
serve path's existing errors (missing run → stderr + exit 2) are unchanged.

## Testing strategy

Headless node guards (the established pattern: stub `global.window`, `require` the real
module, drive the pure `buildCharts`; uPlot/DOM never instantiated). RED-first is not
applicable end-to-end for browser interaction, but the **data-shape contract is fully
node-guardable** and is where the load-bearing behaviour lives:

1. **New `chart_viewer_xmode.mjs` (+ `.rs` shell):** over `sample-traces.json` —
   - `buildCharts(traces, "overlay")` (no `xMode`) ⇒ `data[0]` is the index spine
     `[0,1,…,n-1]` (default is ordinal), and `opts.axes[0].values` is a function (the
     index→label mapper);
   - `buildCharts(traces, "overlay", "continuous")` ⇒ `data[0]` is `traces.xs` verbatim;
   - `buildCharts(traces, "panels")` ⇒ every panel's `opts.cursor.sync.key` is defined and
     equal across panels (crosshair sync);
   - every config carries a `wheelZoomPlugin` entry in `opts.plugins` (interaction wired).
2. **Update `chart_viewer_build.mjs`:** its `data[0] === xs` assertions move to the
   explicit `"continuous"` call; under the default it asserts the index spine. The
   one-chart-overlay / N-panel structure assertions stay.
3. **Update `chart_viewer_gaps.mjs`:** the null-gap-verbatim assertions are on `data[1..]`
   and stay **unchanged in spirit**; only the `data[0] === xs` line is re-pointed (ordinal
   default ⇒ `data[0]` is indices; the gap property is independent of the x spine). The
   "no null coerced to 0, no point dropped" guarantee must remain green.
4. **Rust side:** existing `render_chart_html` tests stay green (the injected
   `window.AURA_TRACES` shape is unchanged); add an assertion that the chart page carries
   the `xmode-toggle` control and that `aura graph`'s page does **not** (no chrome leak).

`cargo test --workspace` green + `cargo clippy --workspace --all-targets -- -D warnings`
exit 0 + a real e2e (`aura run --trace demo && aura chart demo` → a self-contained page
whose injected viewer defaults to ordinal and carries the toggle) gate the cut.

## Acceptance criteria

1. The default served page opens with an **ordinal** (gap-collapsed) x-axis; the data
   array's x spine is `[0..n-1]`, not the raw timestamps.
2. A visible header toggle flips to **continuous** (x = real `xs`) and back; both modes
   render the same series with null gaps intact.
3. In ordinal mode the crosshair/legend reports the **real timestamp** (`xs[i]`) for the
   hovered slot, not the ordinal index.
4. **wheel** zooms the x-axis around the cursor; **drag** pans; **double-click** restores
   the full range.
5. In `--panels` the crosshair is **synchronized** across panels (shared `cursor.sync`).
6. `buildCharts` stays pure and headless-guardable; the new + updated node guards pass and
   the null-gap-verbatim guard stays green.
7. The page remains fully self-contained (no remote `<script src>`; uPlot + data inlined),
   and the chart page wears its own chrome (no `aura graph` leak).