@vimoxshah/tokenflow 1.1.2 → 1.2.0

package/src/ui/views/rhythm.js

@@ -0,0 +1,206 @@
+/**
+ * The Rhythm tab: how the work happens — focus, switching, and when a turn
+ * costs most.
+ *
+ * Derived only from `ctx.bundle.sessions` and the per-hour rollup behind
+ * `ctx.view` (`view.hourly.buckets`, the same rollup the Time patterns tab
+ * charts). All the arithmetic lives in `src/analytics/rhythm.js`, a pure
+ * module with its own tests; this file only turns that into markup.
+ */
+import { el, columns, table, SEQ } from '../charts.js';
+import { filterSessions } from '../../analytics/aggregate.js';
+import { deepWork, switching, costliestHour, focusDays, rhythmSummary } from '../../analytics/rhythm.js';
+
+/** @typedef {import('./index.js').ViewContext} ViewContext */
+
+export const id = 'rhythm';
+export const label = 'Rhythm';
+export const order = 115;
+export const css = './styles/rhythm.css';
+
+// The same number-bolding pass the Overview's story strip uses, so a figure
+// (a number with its unit — "50.0%", "01:00", "$2.10") gets the figure face
+// and the words around it stay words. Copied rather than imported: a view
+// must not import app.js.
+const FIGURE_RE = /((?:\$|[+\-−]|r = )?\d+(?:[.,]\d+)*(?:\s?(?:[KMB](?![a-z])|×|x(?![a-z])|%|days?|hours?|min(?![a-z])))?)/g;
+const STORY_ICONS = ['🎯', '🔀', '💰'];
+
+/**
+ * @param {ViewContext} ctx
+ * @returns {HTMLElement}
+ */
+export function view(ctx) {
+  const { fmt } = ctx;
+  const { compact, usd, pct, int, hourLabel, shortDate, longDate, humanDuration } = fmt;
+  const v = ctx.view;
+
+  // filterSessions applies the date, provider, model and other dimension
+  // filters — the same predicate set the cube uses — but not hourFrom/hourTo:
+  // that filter narrows which token EVENTS count, and a whole session cannot
+  // be half inside an hour window. The banner below says this plainly rather
+  // than letting the hour filter look like it silently does nothing.
+  const sessions = filterSessions(ctx.bundle.sessions || [], ctx.view.filters);
+
+  const deep = deepWork(sessions);
+  const sw = switching(sessions);
+  const costliest = costliestHour(v.hourly?.buckets || []);
+  const focus = focusDays(sessions);
+  const sentences = rhythmSummary({ deep, switching: sw, costliest });
+
+  const root = el('div', { class: 'grid' });
+  root.appendChild(storyStrip(sentences));
+  root.appendChild(el('div', { class: 'banner info' }, [el('span', {
+    text: 'Deep-work, switching and focus-day metrics use sessions filtered by date, provider, model and the other dimension filters. The hour-of-day filter narrows the charts on other tabs but does not apply to a whole session here, so it is left out of these three metrics; the cost-per-hour chart below still follows it.',
+  })]));
+  root.appendChild(kpiCard(ctx, { deep, sw, costliest }, { compact, usd, pct, int, hourLabel, shortDate }));
+  root.appendChild(costliestHourCard(ctx, costliest, { compact, usd, int, hourLabel }));
+  root.appendChild(switchingCard(ctx, sw, { int, shortDate, longDate }));
+  root.appendChild(focusDaysCard(ctx, focus, { compact, pct, int, shortDate, longDate }));
+  return root;
+}
+
+function storyStrip(sentences) {
+  const strip = el('div', { class: 'story' });
+  sentences.forEach((text, i) => {
+    const p = el('p', { class: 'story-text' });
+    let last = 0;
+    for (const m of text.matchAll(FIGURE_RE)) {
+      if (m.index > last) p.appendChild(document.createTextNode(text.slice(last, m.index)));
+      p.appendChild(el('strong', { text: m[0] }));
+      last = m.index + m[0].length;
+    }
+    if (last < text.length) p.appendChild(document.createTextNode(text.slice(last)));
+    strip.appendChild(el('div', { class: 'story-line' }, [
+      el('span', { class: 'story-ico', text: STORY_ICONS[i] || '•', 'aria-hidden': 'true' }),
+      p,
+    ]));
+  });
+  return strip;
+}
+
+function kpiCard(ctx, { deep, sw, costliest }, { compact, usd, pct, int, hourLabel, shortDate }) {
+  const box = el('div', { class: 'cards' });
+  box.appendChild(ctx.kpi('Deep-work sessions', int(deep.count), deep.total ? `${pct(deep.shareOfSessions, 1)} of sessions` : '—'));
+  box.appendChild(ctx.kpi('Share of tokens', pct(deep.shareOfTokens, 1), deep.longest ? `longest ran ${ctx.fmt.humanDuration(deep.longest.durationMs)}` : '—'));
+  box.appendChild(ctx.kpi('Avg project switches / day', sw.average !== null ? sw.average.toFixed(1) : '—', sw.worst ? `worst ${int(sw.worst.switches)} on ${shortDate(sw.worst.date)}` : '—'));
+  const cHour = costliest?.costliest;
+  box.appendChild(ctx.kpi(
+    'Costliest hour',
+    cHour ? `${hourLabel(cHour.hour)}:00` : '—',
+    cHour
+      ? (costliest.metric === 'cost' ? `${usd(cHour.value)} / priced request` : `${compact(cHour.value)} tokens / request`)
+      : (costliest ? 'no priced requests in this slice' : 'not derivable from the aggregate'),
+  ));
+  return ctx.card(
+    'Rhythm at a glance',
+    'Deep work: 45 minutes or more of continuous activity, or 40 or more turns when duration is unknown. Switching: distinct projects touched in a day, minus one. Costliest hour: highest estimated cost per priced request (tokens per request when no price is configured), by hour of day.',
+    box,
+  );
+}
+
+function seqColor(value, max) {
+  if (value === null || value === undefined || !max) return 'var(--hairline)';
+  const t = Math.max(0, Math.min(1, value / max));
+  return SEQ[Math.round(t * (SEQ.length - 1))];
+}
+
+function costliestHourCard(ctx, costliest, { compact, usd, int, hourLabel }) {
+  if (!costliest) {
+    return ctx.card(
+      'Cost per request by hour',
+      'Estimated cost per priced request by hour of day, from the per-hour rollup behind this dashboard.',
+      ctx.emptyCard('Not derivable from the aggregate', 'This slice’s per-hour rollup carries neither a cost nor a token count to divide by requests.'),
+    );
+  }
+  const isCost = costliest.metric === 'cost';
+  const maxV = Math.max(0, ...costliest.hours.map((h) => h.value || 0));
+  const chartData = costliest.hours.map((h) => {
+    const marked = costliest.costliest && h.hour === costliest.costliest.hour;
+    return {
+      label: hourLabel(h.hour) + (marked ? '★' : ''),
+      value: h.value,
+      hour: h.hour,
+      color: seqColor(h.value, maxV),
+      fmtXLong: `${hourLabel(h.hour)}:00${marked ? ', the costliest hour' : ''}`,
+      extra: [{ color: null, name: isCost ? 'Priced requests' : 'Requests', value: int(h.requests) }],
+    };
+  });
+  const hint = !costliest.costliest
+    ? (isCost
+      ? 'ESTIMATE. No priced requests anywhere in this slice, so cost per request is not shown. Configure pricing to see it. Unpriced requests are excluded from the average rather than counted as free.'
+      : 'No requests in this slice.')
+    : (isCost
+      ? `ESTIMATE. Divides estimated cost by PRICED requests only, per hour. An unpriced request is excluded, never counted as free. ★ marks the costliest hour, ${hourLabel(costliest.costliest.hour)}:00.`
+      : `No pricing configured, so this shows tokens per request instead. ★ marks the heaviest hour, ${hourLabel(costliest.costliest.hour)}:00.`);
+  return ctx.chartCard(
+    'rhythm-cost-hour',
+    isCost ? 'Cost per request by hour' : 'Tokens per request by hour',
+    hint,
+    (w) => columns({
+      data: chartData, width: w, height: 220,
+      fmtY: (x) => (isCost ? usd(x) : compact(x)),
+      valueLabel: isCost ? 'Cost / priced request' : 'Tokens / request',
+      ariaLabel: isCost ? 'Estimated cost per priced request by hour of day' : 'Tokens per request by hour of day',
+    }),
+    {
+      columns: [
+        { key: 'hour', label: 'Hour', text: true, value: (r) => hourLabel(r.hour) + ':00' },
+        { key: 'value', label: isCost ? 'Cost / priced request' : 'Tokens / request', value: (r) => (r.value === null ? null : (isCost ? usd(r.value) : compact(r.value))) },
+        { key: 'requests', label: isCost ? 'Priced requests' : 'Requests', value: (r) => int(r.requests) },
+      ],
+      rows: costliest.hours,
+    },
+  );
+}
+
+function switchingCard(ctx, sw, { int, shortDate, longDate }) {
+  if (!sw.days.length) {
+    return ctx.card(
+      'Project switches per day',
+      'Switches = distinct projects touched in a day, minus one. Days with no sessions are not shown.',
+      ctx.emptyCard('No sessions with a known day', 'Project switching needs at least one session with a date in this slice.'),
+    );
+  }
+  const maxSwitch = Math.max(0, ...sw.days.map((d) => d.switches));
+  const data = sw.days.map((d) => ({
+    label: shortDate(d.date), value: d.switches, date: d.date,
+    color: seqColor(d.switches, maxSwitch),
+    fmtXLong: longDate(d.date),
+    extra: [{ color: null, name: 'Projects touched', value: int(d.projects) }],
+  }));
+  return ctx.chartCard(
+    'rhythm-switching',
+    'Project switches per day',
+    'Switches = distinct projects touched that day, minus one. Only days with at least one session are shown; a day with no sessions has no measurable switching, so it is left out rather than shown as zero.',
+    (w) => columns({
+      // Switches are always whole numbers, but the chart's own gridline
+      // picker can land on a half-step for a small max (e.g. 0, 0.5, 1, 1.5,
+      // 2) — rounding those through int() would print "1" twice. Showing the
+      // real half-step value keeps every gridline label distinct.
+      data, width: w, height: 200, fmtY: (x) => (Number.isInteger(x) ? int(x) : x.toFixed(1)), valueLabel: 'Switches',
+      ariaLabel: 'Project switches per day',
+    }),
+    {
+      columns: [
+        { key: 'date', label: 'Date', text: true, value: (r) => longDate(r.date) },
+        { key: 'projects', label: 'Projects touched', value: (r) => int(r.projects) },
+        { key: 'switches', label: 'Switches', value: (r) => int(r.switches) },
+      ],
+      rows: sw.days,
+    },
+  );
+}
+
+function focusDaysCard(ctx, focus, { compact, pct, int, shortDate, longDate }) {
+  const hint = 'Days ranked by the share of that day’s tokens spent in deep-work sessions (45+ minutes continuous, or 40+ turns when duration is unknown). Days with zero tokens are excluded: a 0/0 share is not a real 0%.';
+  if (!focus.length) {
+    return ctx.card('Focus days', hint, ctx.emptyCard('No days to rank', 'Needs at least one session with tokens and a known day in this slice.'));
+  }
+  return ctx.card('Focus days', hint, table([
+    { key: 'date', label: 'Date', text: true, value: (r) => longDate(r.date) },
+    { key: 'share', label: 'Deep-work share of tokens', value: (r) => pct(r.share, 1) },
+    { key: 'deepTokens', label: 'Deep-work tokens', value: (r) => compact(r.deepTokens) },
+    { key: 'total', label: 'Total tokens', value: (r) => compact(r.total) },
+    { key: 'sessions', label: 'Sessions', value: (r) => int(r.sessions) },
+  ], focus, { emptyText: 'No focus days in this slice.' }));
+}

package/src/ui/views/whatif.js

@@ -0,0 +1,196 @@
+/**
+ * The What-if tab: reprice the same tokens at another model's rates.
+ *
+ * This is a what-if about PRICE ONLY. It says nothing about quality, latency
+ * or output length. Swapping a model changes all three, and this tab has no
+ * opinion on any of them.
+ *
+ * Everything here comes from the cube plus the shipped price book, so it
+ * works fully offline. The price book is built the exact same way the Cost
+ * tab builds it (`buildPriceBook(ctx.bundle.pricing || {})`, see
+ * src/analytics/index.js), so the two tabs never disagree about a rate.
+ */
+import { el } from '../charts.js';
+import { buildPriceBook } from '../../core/pricing.js';
+import { reprice, targetModelOptions } from '../../analytics/whatif.js';
+
+/** @typedef {import('./index.js').ViewContext} ViewContext */
+
+export const id = 'whatif';
+export const label = 'What-if';
+export const order = 105;
+export const css = './styles/whatif.css';
+
+/** How many of the current filters' top-cost models get their own row. Matches
+ * the eight-slot series/colour cap used elsewhere in the dashboard. */
+const TOP_N = 8;
+const FLAT_EPSILON = 0.005;
+
+/**
+ * `ctx.S.whatif.mapping` is `{ fromModel: toModel }`, owned by this view, so a
+ * filter change or a re-render never loses the choices already made.
+ * @param {ViewContext} ctx
+ * @returns {{mapping: Record<string,string>}}
+ */
+function state(ctx) {
+  if (!ctx.S.whatif) ctx.S.whatif = { mapping: {} };
+  return ctx.S.whatif;
+}
+
+/**
+ * The top-cost models for the current filters, ranked by the same
+ * `.cost` field the Cost tab ranks and shows. Never re-derived, so the two
+ * tabs list the same models in the same order.
+ * @param {ViewContext} ctx
+ */
+function topModels(ctx) {
+  const models = ctx.view.dimensions.models || [];
+  return [...models]
+    .sort((a, b) => (b.cost ?? -Infinity) - (a.cost ?? -Infinity))
+    .slice(0, TOP_N);
+}
+
+function deltaClass(delta) {
+  if (delta === null || delta === undefined || !Number.isFinite(delta)) return 'whatif-flat';
+  if (Math.abs(delta) < FLAT_EPSILON) return 'whatif-flat';
+  return delta > 0 ? 'whatif-extra' : 'whatif-save';
+}
+
+/** `usd()` never signs a negative value on its own ("$-5.00"); the sign is
+ * what tells savings from extra cost here, so it is added explicitly. A
+ * missing delta delegates straight to `fmt.usd`, so it gets the same
+ * placeholder every other missing value on the dashboard gets. */
+function signedUsd(v, fmt) {
+  if (v === null || v === undefined || !Number.isFinite(v)) return fmt.usd(v);
+  if (Math.abs(v) < FLAT_EPSILON) return fmt.usd(0);
+  const sign = v > 0 ? '+' : '-';
+  return sign + fmt.usd(Math.abs(v));
+}
+
+/**
+ * The target select for one model row: its own model is always an option
+ * (so the identity default always exists, even for an unpriced model), union
+ * the price table's own models and every priced model seen anywhere in the
+ * dataset, grouped into `<optgroup>`s by provider.
+ * @param {ViewContext} ctx
+ * @param {{name:string, provider:string}[]} targetOptions
+ * @param {object} row a `view.dimensions.models` row
+ * @param {number} idx position, for a stable DOM id
+ */
+function targetSelect(ctx, targetOptions, row, idx) {
+  const s = state(ctx);
+  const own = { name: row.key, provider: row.provider || 'Other' };
+  const all = [own, ...targetOptions.filter((o) => o.name !== row.key)];
+  const groups = new Map();
+  for (const o of all) {
+    if (!groups.has(o.provider)) groups.set(o.provider, new Set());
+    groups.get(o.provider).add(o.name);
+  }
+  const sel = el('select', { class: 'whatif-target', id: `whatif-target-${idx}`, 'aria-label': `Reprice ${row.key} at` });
+  for (const provider of [...groups.keys()].sort()) {
+    const grp = el('optgroup', { label: provider });
+    for (const name of [...groups.get(provider)].sort()) grp.appendChild(el('option', { value: name, text: name }));
+    sel.appendChild(grp);
+  }
+  const persisted = s.mapping[row.key];
+  // A persisted target that is no longer offered (e.g. a stale mapping from a
+  // very different dataset) falls back to identity rather than a select that
+  // shows nothing selected.
+  sel.value = persisted && all.some((o) => o.name === persisted) ? persisted : row.key;
+  sel.addEventListener('change', () => {
+    s.mapping[row.key] = sel.value;
+    ctx.rerender({ recompute: false });
+  });
+  return sel;
+}
+
+/** @param {ViewContext} ctx */
+export function view(ctx) {
+  const root = el('div', { class: 'grid whatif' });
+  root.appendChild(ctx.sectionTitle('What-if pricing'));
+  root.appendChild(el('p', { class: 'hint', text: 'This is a what-if about price. It says nothing about quality, latency, or output length.' }));
+
+  const rows = topModels(ctx);
+  if (!rows.length) {
+    root.appendChild(ctx.emptyCard('No priced usage in the current filters.', 'Widen the date range or clear a filter to see models here.'));
+    return root;
+  }
+
+  const book = buildPriceBook(ctx.bundle.pricing || {});
+  const s = state(ctx);
+  const targetOptions = targetModelOptions({ book, seenModels: ctx.view.facets.model || [] });
+  const out = reprice({ rows, book, mapping: s.mapping });
+
+  root.appendChild(kpiRow(ctx, out));
+  root.appendChild(el('p', { class: 'hint whatif-footnote', text: `Estimated from the shipped price table ${book.version}. Same tokens, different rates. Not a claim about quality.` }));
+  if (out.overall.excluded > 0) {
+    root.appendChild(el('p', { class: 'hint whatif-footnote', text: `${out.overall.excluded} model(s) have no source price at all. They show no value and are excluded from the totals above.` }));
+  }
+  root.appendChild(pickerCard(ctx, rows, targetOptions));
+  root.appendChild(deltaChartCard(ctx, out));
+  return root;
+}
+
+function kpiRow(ctx, out) {
+  const { usd } = ctx.fmt;
+  const box = el('div', { class: 'cards' });
+  box.appendChild(ctx.kpi('Current (top models)', usd(out.overall.current), 'at each model\'s own rate'));
+  box.appendChild(ctx.kpi('What-if', usd(out.overall.whatif), 'at the selected targets'));
+  const delta = ctx.kpi('Delta', signedUsd(out.overall.delta, ctx.fmt), out.overall.partial ? 'partial: some rates are missing' : null);
+  delta.classList.add('whatif-delta-kpi', deltaClass(out.overall.delta));
+  box.appendChild(delta);
+  return box;
+}
+
+function pickerCard(ctx, rows, targetOptions) {
+  const body = el('div', { class: 'whatif-pickers' });
+  rows.forEach((row, idx) => {
+    const line = el('div', { class: 'whatif-picker-row' });
+    line.appendChild(el('span', { class: 'whatif-picker-label', text: row.key }));
+    line.appendChild(el('span', { class: 'whatif-picker-arrow', text: '→' }));
+    line.appendChild(targetSelect(ctx, targetOptions, row, idx));
+    body.appendChild(line);
+  });
+  return ctx.card('Reprice at', 'Pick a target model for each of the top models by estimated cost in the current filters. Defaults to the same model, which is a zero delta.', body);
+}
+
+function deltaChartCard(ctx, out) {
+  const { usd, compact } = ctx.fmt;
+  const models = out.models;
+
+  const tableSpec = {
+    columns: [
+      { key: 'model', label: 'Model', text: true },
+      { key: 'target', label: 'Target', text: true },
+      { key: 'tokens', label: 'Tokens', value: (r) => compact(r.tokens) },
+      { key: 'current', label: 'Current', value: (r) => (r.current === null ? null : usd(r.current)) },
+      { key: 'whatif', label: 'What-if', value: (r) => (r.whatif === null ? null : usd(r.whatif)) },
+      { key: 'delta', label: 'Delta', value: (r) => (r.delta === null ? null : signedUsd(r.delta, ctx.fmt)) },
+      { key: 'partial', label: 'Partial', value: (r) => (r.partial ? 'partial' : null) },
+    ],
+    rows: models,
+  };
+  return ctx.chartCard(
+    'whatif-delta',
+    'Delta per model',
+    'What-if minus current, per model. Orange is extra cost, blue is savings.',
+    // hbars' label formatter only ever sees one bar's numeric value, with no
+    // way back to the row, so a null delta is passed through as NaN (falsy,
+    // so it still draws a zero-width bar). `usd()` already renders NaN with
+    // the same placeholder it renders null with, so the label needs no
+    // special-casing here.
+    () => ctx.charts.hbars(models.map((m) => ({
+      label: m.model === m.target ? m.model : `${m.model} → ${m.target}`,
+      value: m.delta === null ? NaN : Math.abs(m.delta),
+      color: deltaClass(m.delta) === 'whatif-extra' ? 'var(--div-1)' : deltaClass(m.delta) === 'whatif-save' ? 'var(--div-5)' : 'var(--div-3)',
+      title: m.partial ? `${m.model}: partial, at least one rate is missing` : m.model,
+      rows: [
+        { color: null, name: 'Tokens', value: compact(m.tokens) },
+        { color: null, name: 'Current', value: usd(m.current) },
+        { color: null, name: 'What-if', value: usd(m.whatif) },
+        { color: null, name: 'Delta', value: signedUsd(m.delta, ctx.fmt) },
+      ],
+    })), { fmt: (v) => usd(v), valueLabel: 'Delta (magnitude)' }),
+    tableSpec,
+  );
+}