@seanmars/tospec 0.14.0 → 0.14.2

package/assets/metrics/app.js

@@ -0,0 +1,995 @@
+// tospec skill-metrics — vanilla page. No framework, no build, no external resources.
+// Charts: vendored Chart.js (assets/chart.umd.js), themed via CSS variables.
+//
+// This file holds no statistics: every total, median, and bucket arrives
+// already computed, so there is no second definition of any summary to drift
+// from the server's.
+
+const view = document.getElementById('view');
+
+const MS_PER_MINUTE = 60000;
+
+// --- persisted preferences -------------------------------------------------
+//
+// With the command's data flags gone this is the only channel a preference has:
+// without it, anyone who keeps split-gap at 60 would re-set four controls on
+// every invocation.
+
+const PREFS_KEY = 'tospec-metrics';
+
+function loadPrefs() {
+  try {
+    return JSON.parse(localStorage.getItem(PREFS_KEY)) || {};
+  } catch {
+    return {};
+  }
+}
+
+function savePrefs(prefs) {
+  try {
+    localStorage.setItem(PREFS_KEY, JSON.stringify(prefs));
+  } catch {
+    // Private browsing or a full quota: preferences are a convenience, never a
+    // precondition for the page working.
+  }
+}
+
+// --- language --------------------------------------------------------------
+//
+// Every string the page shows lives here. Skill names are identifiers and are
+// never translated — they name real files and commands.
+//
+// Traditional Chinese (Taiwan) uses half-width punctuation, matching the rest of
+// the project's prose.
+
+const STRINGS = {
+  en: {
+    'lang.name': 'English',
+    'control.range': 'Range',
+    'control.idleGap': 'Idle gap (min)',
+    'control.splitGap': 'Split gap (min)',
+    'control.workflowsOnly': 'tospec workflows only',
+    'control.theme': 'Theme',
+    'control.language': 'Language',
+    'control.refresh': '↻ Refresh',
+    'range.30': 'Last 30 days',
+    'range.90': 'Last 90 days',
+    'range.365': 'Last year',
+    'range.all': 'All time',
+    'theme.system': 'System',
+    'theme.light': 'Light',
+    'theme.dark': 'Dark',
+    'theme.dracula': 'Dracula',
+    'chart.totals.title': 'Total time by skill',
+    'chart.totals.note': 'Solid is engaged time; the recessed part is idle — pauses inside a run.',
+    'chart.totals.axis': 'minutes — ordered by engaged time',
+    'chart.median.title': 'Typical run length',
+    'chart.median.note':
+      'The middle run of each skill. A skill can top the totals above and sit low here — that is a lot of short runs, not a slow one.',
+    'chart.median.axis': 'median minutes per run — ordered by engaged',
+    'chart.distribution.title': 'Per-run distribution',
+    'chart.distribution.note':
+      'Every dot is one run. The bar spans shortest to longest; the solid part is the engaged range.',
+    'chart.distribution.axis': 'minutes per run',
+    'chart.series.title.day': 'Time per day',
+    'chart.series.title.week': 'Time per week',
+    'chart.series.title.month': 'Time per month',
+    'chart.series.note.day': 'Local calendar time. A run counts whole on the day it started.',
+    'chart.series.note.week': 'Local calendar time. A run counts whole on the week it started.',
+    'chart.series.note.month': 'Local calendar time. A run counts whole on the month it started.',
+    'chart.series.axis': 'engaged minutes',
+    'chart.timeline.title': 'Run timeline',
+    'chart.timeline.note':
+      'One bubble per run; its area is engaged time. Overlapping runs are nudged apart, always by the same amount.',
+    'series.engaged': 'engaged',
+    'series.idle': 'idle',
+    'series.medianSpan': 'median span',
+    'series.medianEngaged': 'median engaged',
+    'series.spanRange': 'span range',
+    'series.engagedRange': 'engaged range',
+    'series.eachRun': 'each run',
+    'empty.noHistory.title': 'No history for this project',
+    'empty.noHistory.body': '{tool} — looked in: {dir}',
+    'empty.noAttribution.title': 'No skill runs recorded',
+    'empty.noAttribution.body': 'Scanned {sessions} session(s), none with skill attribution.',
+    'empty.noAttribution.hint':
+      'Skill attribution only appears in recent sessions; older ones cannot be measured.',
+    'empty.noRange.title': 'Nothing in this range',
+    'empty.noRange.body':
+      'The transcripts hold {sessions} attributed session(s) — this time range just has none of them.',
+    'empty.allHidden.title': 'Everything is hidden',
+    'empty.allHidden.body':
+      'No tospec workflow ran in this range. Untick "tospec workflows only" to see the rest.',
+    'error.title': 'Could not load the report',
+    'footer.source':
+      '{tool}: derived from {attributed}/{sessions} session(s) with skill attribution{span}.',
+    'footer.noSource': '{tool}: no history found for this project.',
+    'footer.codexCaveat': 'Skill attribution here is inferred from SKILL.md reads, not recorded directly.',
+    'footer.sourceSpan': ', {first} to {last}',
+    'footer.definition':
+      'A run is one stretch of a single skill, uninterrupted by another skill and with no pause longer than the split gap ({split} min). Idle is the time inside a run spent paused for longer than the idle gap ({idle} min).',
+  },
+  'zh-TW': {
+    'lang.name': '正體中文',
+    'control.range': '時間範圍',
+    'control.idleGap': '閒置間隔 (分)',
+    'control.splitGap': '切分間隔 (分)',
+    'control.workflowsOnly': '只看 tospec workflow',
+    'control.theme': '主題',
+    'control.language': '語言',
+    'control.refresh': '↻ 重新讀取',
+    'range.30': '最近 30 天',
+    'range.90': '最近 90 天',
+    'range.365': '最近一年',
+    'range.all': '全部時間',
+    'theme.system': '跟隨系統',
+    'theme.light': '淺色',
+    'theme.dark': '深色',
+    'theme.dracula': 'Dracula',
+    'chart.totals.title': '各 Skill 的總投入時間',
+    'chart.totals.note': '實色為實際工作時間, 凹陷部分為閒置 — 也就是一次執行之中的停頓.',
+    'chart.totals.axis': '分鐘 — 依實際工作時間排序',
+    'chart.median.title': '典型的單次時長',
+    'chart.median.note':
+      '每個 Skill 的中位數. 一個 Skill 可能在上面的總量排第一, 在這裡卻很低 — 那代表次數多而不是每次慢.',
+    'chart.median.axis': '每次執行的中位數分鐘 — 依實際工作時間排序',
+    'chart.distribution.title': '每次執行的分佈',
+    'chart.distribution.note':
+      '每一個點是一次執行. 長條從最短跨到最長, 實色部分是實際工作時間的範圍.',
+    'chart.distribution.axis': '每次執行的分鐘數',
+    'chart.series.title.day': '每日投入時間',
+    'chart.series.title.week': '每週投入時間',
+    'chart.series.title.month': '每月投入時間',
+    'chart.series.note.day': '依本地時間計算. 一次執行整筆算在它開始的那一天.',
+    'chart.series.note.week': '依本地時間計算. 一次執行整筆算在它開始的那一週.',
+    'chart.series.note.month': '依本地時間計算. 一次執行整筆算在它開始的那個月.',
+    'chart.series.axis': '實際工作分鐘數',
+    'chart.timeline.title': '執行時間軸',
+    'chart.timeline.note':
+      '一次執行一個圓, 面積代表實際工作時間. 重疊的執行會被錯開, 而且每次錯開的位置都相同.',
+    'series.engaged': '實際工作',
+    'series.idle': '閒置',
+    'series.medianSpan': '總時長中位數',
+    'series.medianEngaged': '實際工作中位數',
+    'series.spanRange': '總時長範圍',
+    'series.engagedRange': '實際工作範圍',
+    'series.eachRun': '每次執行',
+    'empty.noHistory.title': '這個專案沒有歷史紀錄',
+    'empty.noHistory.body': '{tool} — 找過的位置: {dir}',
+    'empty.noAttribution.title': '沒有任何 Skill 執行紀錄',
+    'empty.noAttribution.body': '掃描了 {sessions} 個 session, 沒有任何一個帶有 Skill 歸屬資訊.',
+    'empty.noAttribution.hint':
+      'Skill 歸屬資訊只存在於較新的 session, 舊的紀錄無法回溯統計.',
+    'empty.noRange.title': '這個時間範圍內沒有資料',
+    'empty.noRange.body': 'Transcript 裡有 {sessions} 個帶歸屬資訊的 session, 只是都不在這個範圍內.',
+    'empty.allHidden.title': '全部都被隱藏了',
+    'empty.allHidden.body': '這個範圍內沒有 tospec workflow 執行過. 取消勾選「只看 tospec workflow」即可看到其餘的.',
+    'error.title': '無法載入報表',
+    'footer.source': '{tool}: 取自 {attributed}/{sessions} 個帶有 Skill 歸屬資訊的 session{span}.',
+    'footer.noSource': '{tool}: 這個專案沒有找到歷史紀錄.',
+    'footer.codexCaveat': '這裡的 Skill 歸屬資訊是從 SKILL.md 讀取行為推論出來的, 並非直接記錄.',
+    'footer.sourceSpan': ', {first} 至 {last}',
+    'footer.definition':
+      '一次執行是指單一 Skill 連續進行的一段, 中間沒有被其他 Skill 打斷, 也沒有超過切分間隔 ({split} 分) 的停頓. 閒置則是一次執行之中, 停頓超過閒置間隔 ({idle} 分) 的那些時間.',
+  },
+};
+
+const LOCALES = Object.keys(STRINGS);
+
+/** Looks up a string and fills `{name}` placeholders. Falls back to English. */
+function t(key, vars) {
+  const table = STRINGS[controls.language] || STRINGS.en;
+  const raw = table[key] ?? STRINGS.en[key] ?? key;
+  if (!vars) return raw;
+  return raw.replace(/\{(\w+)\}/g, (_, name) => (name in vars ? String(vars[name]) : `{${name}}`));
+}
+
+// --- tiny helpers ----------------------------------------------------------
+
+async function api(path) {
+  const res = await fetch(path);
+  if (!res.ok) {
+    let detail = 'HTTP ' + res.status;
+    try {
+      const body = await res.json();
+      if (body && body.error) detail = body.error;
+    } catch {
+      // no JSON body; keep the status line
+    }
+    throw new Error(detail);
+  }
+  return res.json();
+}
+
+/** Minimal DOM builder; all text goes in as textContent (XSS-safe). */
+function el(tag, props = {}, children = []) {
+  const node = document.createElement(tag);
+  for (const [k, v] of Object.entries(props)) {
+    if (v == null) continue;
+    if (k === 'class') node.className = v;
+    else if (k === 'text') node.textContent = v;
+    else node.setAttribute(k, v);
+  }
+  for (const child of [].concat(children)) {
+    if (child == null) continue;
+    node.append(child.nodeType ? child : document.createTextNode(String(child)));
+  }
+  return node;
+}
+
+const minutes = (ms) => ms / MS_PER_MINUTE;
+
+/** The agent a row's figures came from, as it appears in that row's label. */
+const SOURCE_LABEL = { 'claude-code': 'Claude', codex: 'Codex' };
+
+/**
+ * Skills that are not tospec's own workflows keep the marker the table used.
+ * Colour alone must never be what tells them apart.
+ *
+ * Every row also names its agent, including Claude Code's. Marking only Codex
+ * left the other source implicit, so an unsuffixed row read as "the skill"
+ * rather than "the skill, as measured by one of two agents" — and the two are
+ * never summed, which only makes sense once both are visibly one agent's
+ * figures. Naming both also keeps the distinction textual rather than a colour
+ * difference, the same convention the non-workflow marker follows.
+ */
+function skillLabel(s) {
+  const base = s.workflow ? s.skill : s.skill + ' *';
+  return base + ' (' + (SOURCE_LABEL[s.source] || s.source) + ')';
+}
+
+/**
+ * The composite key identifying one report row: a skill under one source.
+ * Mirrors `skillRowKey` in src/core/skill-metrics.ts exactly — this file
+ * cannot import that TS module, so the format is reproduced here rather than
+ * shared.
+ */
+function rowKey(skill, source) {
+  return skill + '::' + source;
+}
+
+// --- charts ----------------------------------------------------------------
+
+const hasChart = typeof Chart !== 'undefined';
+const liveCharts = new Set();
+
+// Axis ticks, legends, and axis titles are drawn onto the canvas by Chart.js and
+// never see a stylesheet, so the page's type scale has to be applied here too —
+// otherwise the text covering most of the page stays at Chart.js's 12px default
+// while everything around it grows.
+if (hasChart) Chart.defaults.font.size = 14;
+
+function cssVar(name) {
+  return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+}
+
+function newChart(canvas, config) {
+  const chart = new Chart(canvas, config);
+  liveCharts.add(chart);
+  return chart;
+}
+
+function chartTheme() {
+  return {
+    muted: cssVar('--muted'),
+    grid: cssVar('--border'),
+    engaged: cssVar('--engaged'),
+    idle: cssVar('--idle'),
+    point: cssVar('--point'),
+    pointSoft: cssVar('--point-soft'),
+    ramp: ['--ramp-1', '--ramp-2', '--ramp-3', '--ramp-4', '--ramp-5', '--ramp-6'].map(cssVar),
+  };
+}
+
+/**
+ * Total time per skill: engaged solid, idle recessed, so the whole bar is the
+ * wall-clock span.
+ *
+ * Rows arrive ordered by engaged total and are drawn in that order. Because the
+ * bar's full length is span, those totals are not monotonic — a skill can sort
+ * last and still have the longest bar. The recessed idle segment is what keeps
+ * that readable: the solid segments' end points form a descending staircase,
+ * and the axis title says that staircase is the sort key.
+ */
+function buildTotalsChart(canvas, skills) {
+  const theme = chartTheme();
+  return newChart(canvas, {
+    type: 'bar',
+    data: {
+      labels: skills.map(skillLabel),
+      datasets: [
+        {
+          label: t('series.engaged'),
+          data: skills.map((s) => minutes(s.engaged.totalMs)),
+          backgroundColor: theme.engaged,
+        },
+        {
+          label: t('series.idle'),
+          data: skills.map((s) => minutes(s.span.totalMs - s.engaged.totalMs)),
+          backgroundColor: theme.idle,
+        },
+      ],
+    },
+    options: {
+      indexAxis: 'y',
+      responsive: true,
+      maintainAspectRatio: false,
+      scales: {
+        x: {
+          stacked: true,
+          beginAtZero: true,
+          title: { display: true, text: t('chart.totals.axis'), color: theme.muted },
+          ticks: { color: theme.muted },
+          grid: { color: theme.grid },
+        },
+        y: {
+          stacked: true,
+          ticks: { color: theme.muted },
+          grid: { display: false },
+        },
+      },
+      plugins: {
+        legend: { labels: { color: theme.muted } },
+      },
+    },
+  });
+}
+
+/**
+ * The middle run of each skill, span and engaged side by side.
+ *
+ * Deliberately **not** stacked. Stacking would present
+ * `median(span) - median(engaged)` as a median idle time, and it is not one —
+ * the difference of two medians is not the median of the differences. The bars
+ * never invert (the k-th smallest engaged time is at most the k-th smallest
+ * span), but that is a fact about their lengths, not a licence to subtract them.
+ *
+ * Ordered by engaged total like the chart above, so the two read as the same
+ * list twice — which is what makes "high total, low median" visible as a shape
+ * rather than something to work out.
+ */
+function buildMedianChart(canvas, skills) {
+  const theme = chartTheme();
+  return newChart(canvas, {
+    type: 'bar',
+    data: {
+      labels: skills.map(skillLabel),
+      datasets: [
+        {
+          label: t('series.medianEngaged'),
+          data: skills.map((s) => minutes(s.engaged.medianMs)),
+          backgroundColor: theme.engaged,
+        },
+        {
+          label: t('series.medianSpan'),
+          data: skills.map((s) => minutes(s.span.medianMs)),
+          backgroundColor: theme.idle,
+        },
+      ],
+    },
+    options: {
+      indexAxis: 'y',
+      responsive: true,
+      maintainAspectRatio: false,
+      scales: {
+        x: {
+          beginAtZero: true,
+          title: { display: true, text: t('chart.median.axis'), color: theme.muted },
+          ticks: { color: theme.muted },
+          grid: { color: theme.grid },
+        },
+        y: { ticks: { color: theme.muted }, grid: { display: false } },
+      },
+      plugins: { legend: { labels: { color: theme.muted } } },
+    },
+  });
+}
+
+/**
+ * Per-run distribution: one row per skill, the span range as a recessed
+ * backdrop, the engaged range solid over it, and every individual run as a dot.
+ *
+ * The two ranges share a row rather than getting one each. Every run's engaged
+ * time is at most its span, so a skill's engaged range is contained by its span
+ * range at both ends and neither can occlude the other; where a skill's runs all
+ * have equal span and engaged time the two coincide and read as a single bar,
+ * which is honest — they are the same numbers.
+ *
+ * The dots are what carry the shape a median and a maximum discard, and they are
+ * also what keeps a zero-length run visible: its range bar has no width, but its
+ * dot sits at zero like any other.
+ */
+function buildDistributionChart(canvas, skills, runs) {
+  const theme = chartTheme();
+  const labels = skills.map(skillLabel);
+  // Keyed by skill-and-source, not skill alone: a skill with runs from both
+  // sources gets two rows, and a run must land on its own source's row only.
+  const rowOf = new Map(skills.map((s, i) => [rowKey(s.skill, s.source), i]));
+
+  const range = (stats) => [minutes(stats.minMs), minutes(stats.maxMs)];
+
+  return newChart(canvas, {
+    type: 'bar',
+    data: {
+      labels,
+      datasets: [
+        {
+          label: t('series.spanRange'),
+          data: skills.map((s) => range(s.span)),
+          backgroundColor: theme.idle,
+          // Overlaid, not placed side by side: both bars describe the same row.
+          grouped: false,
+          barPercentage: 0.8,
+        },
+        {
+          label: t('series.engagedRange'),
+          data: skills.map((s) => range(s.engaged)),
+          backgroundColor: theme.engaged,
+          grouped: false,
+          barPercentage: 0.45,
+        },
+        {
+          type: 'scatter',
+          label: t('series.eachRun'),
+          data: runs
+            .filter((r) => rowOf.has(rowKey(r.skill, r.source)))
+            .map((r) => ({ x: minutes(r.engagedMs), y: labels[rowOf.get(rowKey(r.skill, r.source))] })),
+          backgroundColor: theme.point,
+          pointRadius: 3,
+        },
+      ],
+    },
+    options: {
+      indexAxis: 'y',
+      responsive: true,
+      maintainAspectRatio: false,
+      scales: {
+        x: {
+          beginAtZero: true,
+          title: { display: true, text: t('chart.distribution.axis'), color: theme.muted },
+          ticks: { color: theme.muted },
+          grid: { color: theme.grid },
+        },
+        y: { ticks: { color: theme.muted }, grid: { display: false } },
+      },
+      plugins: { legend: { labels: { color: theme.muted } } },
+    },
+  });
+}
+
+/**
+ * Engaged time per period, stacked by skill. Buckets, their local dates, and the
+ * granularity all arrive decided — the page only draws them.
+ */
+function buildSeriesChart(canvas, series, skills) {
+  const theme = chartTheme();
+  // A stacked series needs a colour per skill rather than the two-token pair the
+  // other charts use, so it walks a fixed ramp. Order matches the ranking, so
+  // the largest contributors keep the strongest colours.
+  const ramp = theme.ramp;
+  return newChart(canvas, {
+    type: 'bar',
+    data: {
+      labels: series.buckets.map((b) => b.key),
+      datasets: skills.map((s, i) => ({
+        label: skillLabel(s),
+        // Keyed by skill-and-source: a bucket keeps the two sources' engaged
+        // time for the same skill apart rather than summing them.
+        data: series.buckets.map((b) => minutes(b.byRow[rowKey(s.skill, s.source)] || 0)),
+        backgroundColor: ramp[i % ramp.length],
+      })),
+    },
+    options: {
+      responsive: true,
+      maintainAspectRatio: false,
+      interaction: { mode: 'index', intersect: false },
+      scales: {
+        x: { stacked: true, ticks: { color: theme.muted, maxRotation: 0, autoSkip: true }, grid: { display: false } },
+        y: {
+          stacked: true,
+          beginAtZero: true,
+          title: { display: true, text: t('chart.series.axis'), color: theme.muted },
+          ticks: { color: theme.muted },
+          grid: { color: theme.grid },
+        },
+      },
+      plugins: { legend: { labels: { color: theme.muted, boxWidth: 12 } } },
+    },
+  });
+}
+
+/**
+ * Stable offset in [-0.28, 0.28] for one run, derived from its session and index.
+ *
+ * Never random: switching themes rebuilds every chart, because Chart.js reads
+ * CSS variables when a chart is constructed. A random offset would put every
+ * point somewhere new on rebuild, which reads as the data having changed.
+ */
+function stableJitter(run, index) {
+  const seed = run.session + ':' + index;
+  let h = 5381;
+  for (let i = 0; i < seed.length; i++) h = ((h << 5) + h + seed.charCodeAt(i)) | 0;
+  return ((Math.abs(h) % 1000) / 1000 - 0.5) * 0.56;
+}
+
+/** Follows the selected language, so an axis never labels itself in another one. */
+const dayLabel = (ms) =>
+  new Date(ms).toLocaleDateString(controls.language, { month: 'short', day: 'numeric' });
+
+/**
+ * Every run on a time axis, one row per skill. Bubble area — not radius —
+ * carries engaged time, which is the mapping the eye actually reads.
+ *
+ * A `linear` x scale over raw milliseconds, not Chart.js's `time` scale: that
+ * one needs a date adapter this page does not ship, and tick formatting is all
+ * this needs from it.
+ *
+ * No cap on how many runs are drawn. Overlap is handled by transparency and the
+ * offset above; the range control is the lever if a history ever gets too dense.
+ */
+function buildTimelineChart(canvas, skills, runs) {
+  const theme = chartTheme();
+  const labels = skills.map(skillLabel);
+  const rowOf = new Map(skills.map((s, i) => [rowKey(s.skill, s.source), i]));
+  const peak = Math.max(1, ...runs.map((r) => r.engagedMs));
+
+  return newChart(canvas, {
+    type: 'bubble',
+    data: {
+      datasets: [
+        {
+          label: t('series.eachRun'),
+          data: runs
+            .filter((r) => rowOf.has(rowKey(r.skill, r.source)))
+            .map((r, i) => ({
+              x: r.startMs,
+              y: rowOf.get(rowKey(r.skill, r.source)) + stableJitter(r, i),
+              // Area proportional to engaged time, so radius follows its root.
+              r: 3 + 9 * Math.sqrt(r.engagedMs / peak),
+              skill: r.skill,
+              source: r.source,
+              session: r.session,
+            })),
+          backgroundColor: theme.pointSoft,
+        },
+      ],
+    },
+    options: {
+      responsive: true,
+      maintainAspectRatio: false,
+      scales: {
+        x: {
+          type: 'linear',
+          ticks: { color: theme.muted, maxRotation: 0, callback: (v) => dayLabel(v) },
+          grid: { color: theme.grid },
+        },
+        y: {
+          type: 'category',
+          labels,
+          offset: true,
+          ticks: { color: theme.muted },
+          grid: { display: false },
+        },
+      },
+      plugins: { legend: { display: false } },
+    },
+  });
+}
+
+// --- render ----------------------------------------------------------------
+
+// A chart with `maintainAspectRatio: false` fills whatever height its container
+// has, so a fixed container squeezes every row thinner as skills accumulate.
+// Four of the five charts put one skill per row, so their height has to be
+// computed from the row count and the page allowed to scroll — which is the
+// trade already chosen over capping how many skills are shown.
+
+/** One skill row: enough for a 14px label plus breathing room. */
+const ROW_PX = 32;
+/** Bubbles are offset vertically and can reach 24px across, so rows need more. */
+const TIMELINE_ROW_PX = 44;
+/** Axis labels, legend, and axis title, which do not grow with the rows. */
+const CHART_CHROME_PX = 78;
+const MIN_CHART_PX = 220;
+
+function heightForRows(rows, rowPx = ROW_PX) {
+  return Math.max(MIN_CHART_PX, CHART_CHROME_PX + rows * rowPx);
+}
+
+/**
+ * `height` is the container's pixel height. Charts whose y axis is a skill pass
+ * one derived from the row count; the per-period series does not — its y axis is
+ * minutes, so more skills only add segments to bars that already have room.
+ */
+function chartPanel(title, note, height) {
+  const canvas = el('canvas');
+  const wrap = el('div', { class: 'chart' }, canvas);
+  wrap.style.height = height + 'px';
+  const panel = el('section', { class: 'panel' }, [
+    el('h2', { text: title }),
+    note ? el('p', { class: 'panel-note', text: note }) : null,
+    wrap,
+  ]);
+  return { panel, canvas };
+}
+
+// --- controls --------------------------------------------------------------
+
+/**
+ * Every control here changes what is computed, so each one is a request. The
+ * range is a browsing choice; the two gaps re-bound what a run even is. None of
+ * them is applied in this file — the page holds no statistics.
+ */
+const controls = {
+  rangeDays: 'all', // '30' | '90' | '365' | 'all' — all-time is what the page opens on
+  idleGapMs: 5 * 60000,
+  splitGapMs: 30 * 60000,
+  /** View-only: hides rows, changes nothing that was computed. */
+  workflowsOnly: false,
+  theme: 'system', // system | light | dark | dracula
+  /** View-only: wording changes nothing that was computed. */
+  language: 'en', // en | zh-TW
+  ...loadPrefs(),
+};
+
+function applyLanguage(locale) {
+  document.documentElement.setAttribute('lang', locale);
+}
+
+applyLanguage(controls.language);
+
+function setControl(key, value, recompute) {
+  controls[key] = value;
+  savePrefs(controls);
+  if (recompute) void load();
+  else render();
+}
+
+// --- theme -----------------------------------------------------------------
+
+const systemDark =
+  typeof window !== 'undefined' && window.matchMedia
+    ? window.matchMedia('(prefers-color-scheme: dark)')
+    : { matches: false, addEventListener() {} };
+
+/** 'system' resolves against the OS; the rest map straight to a data-theme value. */
+function applyTheme(choice) {
+  const resolved = choice === 'system' ? (systemDark.matches ? 'dark' : 'light') : choice;
+  document.documentElement.setAttribute('data-theme', resolved);
+}
+
+applyTheme(controls.theme);
+systemDark.addEventListener('change', () => {
+  if (controls.theme === 'system') {
+    applyTheme('system');
+    render(); // charts read CSS variables when constructed, so they must be rebuilt
+  }
+});
+
+function reportQuery(refresh) {
+  const params = new URLSearchParams({
+    idleGap: String(controls.idleGapMs),
+    splitGap: String(controls.splitGapMs),
+  });
+  if (controls.rangeDays !== 'all') {
+    params.set('since', String(Date.now() - Number(controls.rangeDays) * 86400000));
+  }
+  if (refresh) params.set('refresh', '1');
+  return params;
+}
+
+function labelled(text, input) {
+  return el('label', { class: 'control' }, [el('span', { text }), input]);
+}
+
+function select(options, value, onChange) {
+  const node = el('select');
+  for (const [v, text] of options) {
+    const option = el('option', { value: v, text });
+    if (v === value) option.setAttribute('selected', 'selected');
+    node.append(option);
+  }
+  node.value = value;
+  node.addEventListener('change', () => onChange(node.value));
+  return node;
+}
+
+function minutesInput(valueMs, onChange) {
+  const node = el('input', { type: 'number', min: '1', step: '1', class: 'gap' });
+  node.value = String(minutes(valueMs));
+  node.addEventListener('change', () => {
+    const n = Number(node.value);
+    // The server refuses non-positive values; not sending them keeps the page
+    // from flashing an error the user cannot act on.
+    if (Number.isFinite(n) && n > 0) onChange(n * MS_PER_MINUTE);
+    else node.value = String(minutes(valueMs));
+  });
+  return node;
+}
+
+function checkbox(text, checked, onChange) {
+  const input = el('input', { type: 'checkbox' });
+  input.checked = checked;
+  input.addEventListener('change', () => onChange(input.checked));
+  return el('label', { class: 'control control-inline' }, [input, el('span', { text })]);
+}
+
+function renderControls() {
+  return el('section', { class: 'controls' }, [
+    labelled(
+      t('control.range'),
+      select(
+        [
+          ['30', t('range.30')],
+          ['90', t('range.90')],
+          ['365', t('range.365')],
+          ['all', t('range.all')],
+        ],
+        controls.rangeDays,
+        (v) => setControl('rangeDays', v, true)
+      )
+    ),
+    labelled(
+      t('control.idleGap'),
+      minutesInput(controls.idleGapMs, (ms) => setControl('idleGapMs', ms, true))
+    ),
+    labelled(
+      t('control.splitGap'),
+      minutesInput(controls.splitGapMs, (ms) => setControl('splitGapMs', ms, true))
+    ),
+    // View-only, so no request: each skill's statistics are computed
+    // independently of every other skill's, and hiding a row cannot alter them.
+    checkbox(t('control.workflowsOnly'), controls.workflowsOnly, (on) =>
+      setControl('workflowsOnly', on, false)
+    ),
+    // Everything from here sits at the right: what the page shows, rather than
+    // what it computes.
+    el('div', { class: 'controls-right' }, [
+      labelled(
+        t('control.theme'),
+        select(
+          [
+            ['system', t('theme.system')],
+            ['light', t('theme.light')],
+            ['dark', t('theme.dark')],
+            ['dracula', t('theme.dracula')],
+          ],
+          controls.theme,
+          (v) => {
+            applyTheme(v);
+            setControl('theme', v, false);
+          }
+        )
+      ),
+      // View-only like the theme: wording changes nothing that was computed.
+      labelled(
+        t('control.language'),
+        select(
+          LOCALES.map((code) => [code, STRINGS[code]['lang.name']]),
+          controls.language,
+          (v) => {
+            applyLanguage(v);
+            setControl('language', v, false);
+          }
+        )
+      ),
+      // The report measures the session viewing it, so what is on screen goes
+      // stale while it is being read. This is the only way to pick that up: every
+      // other control recomputes from the parse taken when the server started.
+      refreshButton(),
+    ]),
+  ]);
+}
+
+function refreshButton() {
+  const button = el('button', { type: 'button', class: 'refresh', text: t('control.refresh') });
+  button.addEventListener('click', () => void load(true));
+  return button;
+}
+
+/**
+ * Applies the view-only controls. Nothing here recomputes: hiding a skill's row
+ * cannot change any other skill's numbers, because each skill's statistics are
+ * derived from its own runs alone.
+ */
+function visible(report) {
+  if (!controls.workflowsOnly) return report;
+  const skills = report.skills.filter((s) => s.workflow);
+  const kept = new Set(skills.map((s) => s.skill));
+  return { ...report, skills, runs: report.runs.filter((r) => kept.has(r.skill)) };
+}
+
+// --- empty states and footer -----------------------------------------------
+
+function note(title, ...lines) {
+  return el('section', { class: 'panel' }, [
+    el('h2', { text: title }),
+    ...lines.filter(Boolean).map((text) => el('p', { class: 'panel-note', text })),
+  ]);
+}
+
+/**
+ * Why a report is empty, or null when it is not.
+ *
+ * The three outcomes are genuinely different and the old table conflated the
+ * last two: no history at all, history that predates skill attribution, and a
+ * range that happens to hold nothing. Saying "no history" for the third would
+ * send someone looking for a missing directory that is right there.
+ *
+ * Claude Code and Codex are scanned independently, so these three outcomes are
+ * evaluated across both combined — one source having history says nothing
+ * about the other (which source is missing, if any, is what the per-source
+ * footer line says instead; this state only fires when *neither* has anything
+ * to show).
+ */
+function emptyState(full, shown) {
+  const { claudeCode, codex } = full.sources;
+  if (!claudeCode.available && !codex.available) {
+    return note(
+      t('empty.noHistory.title'),
+      t('empty.noHistory.body', { tool: 'Claude Code', dir: claudeCode.transcriptDir }),
+      t('empty.noHistory.body', { tool: 'Codex', dir: codex.transcriptDir })
+    );
+  }
+  const attributedSessions = claudeCode.attributedSessions + codex.attributedSessions;
+  const sessions = claudeCode.sessions + codex.sessions;
+  if (attributedSessions === 0) {
+    return note(
+      t('empty.noAttribution.title'),
+      t('empty.noAttribution.body', { sessions }),
+      t('empty.noAttribution.hint')
+    );
+  }
+  if (full.skills.length === 0) {
+    return note(t('empty.noRange.title'), t('empty.noRange.body', { sessions: attributedSessions }));
+  }
+  if (shown.skills.length === 0) {
+    return note(t('empty.allHidden.title'), t('empty.allHidden.body'));
+  }
+  return null;
+}
+
+/**
+ * One source's line: its usual stats sentence, or — when this source has
+ * nothing for this project — a plain statement of that fact rather than
+ * silently rendering as if the source did not exist (codex-metrics-source
+ * spec, "A project with no matching Codex sessions..."). Codex's line always
+ * carries the heuristic-attribution caveat, wherever Codex figures are shown.
+ */
+function sourceFooterLine(tool, source) {
+  if (!source.available || source.sessions === 0) {
+    return t('footer.noSource', { tool });
+  }
+  const span =
+    source.firstSeen && source.lastSeen
+      ? t('footer.sourceSpan', {
+          first: source.firstSeen.slice(0, 10),
+          last: source.lastSeen.slice(0, 10),
+        })
+      : '';
+  const base = t('footer.source', {
+    tool,
+    attributed: source.attributedSessions,
+    sessions: source.sessions,
+    span,
+  });
+  return tool === 'Codex' ? base + ' ' + t('footer.codexCaveat') : base;
+}
+
+function footer(report) {
+  const { claudeCode, codex } = report.sources;
+  return el('section', { class: 'footer' }, [
+    el('p', { text: sourceFooterLine('Claude Code', claudeCode) }),
+    el('p', { text: sourceFooterLine('Codex', codex) }),
+    // Without this, one skill showing up as several runs looks like a bug rather
+    // than the split gap doing its job. The current values, not fixed ones —
+    // both are adjustable, so a hard-coded "30 min" would start lying.
+    el('p', {
+      text: t('footer.definition', {
+        split: minutes(report.thresholds.splitGapMs),
+        idle: minutes(report.thresholds.idleGapMs),
+      }),
+    }),
+  ]);
+}
+
+function renderReport(full) {
+  const report = visible(full);
+  view.replaceChildren();
+  view.append(renderControls());
+
+  const empty = emptyState(full, report);
+  if (empty) {
+    view.append(empty);
+    if (full.sources.claudeCode.available || full.sources.codex.available) view.append(footer(full));
+    return;
+  }
+
+  const rows = report.skills.length;
+
+  const totals = chartPanel(
+    t('chart.totals.title'),
+    t('chart.totals.note'),
+    heightForRows(rows)
+  );
+  view.append(totals.panel);
+  if (hasChart) buildTotalsChart(totals.canvas, report.skills);
+
+  // Straight after the totals, because "how much in all" and "how long each
+  // time" are the pair that explain each other.
+  const median = chartPanel(
+    t('chart.median.title'),
+    t('chart.median.note'),
+    // Two bars per skill rather than one stacked bar, so each row needs more.
+    heightForRows(rows, ROW_PX * 1.5)
+  );
+  view.append(median.panel);
+  if (hasChart) buildMedianChart(median.canvas, report.skills);
+
+  const distribution = chartPanel(
+    t('chart.distribution.title'),
+    t('chart.distribution.note'),
+    heightForRows(rows)
+  );
+  view.append(distribution.panel);
+  if (hasChart) buildDistributionChart(distribution.canvas, report.skills, report.runs);
+
+  const period = report.series.granularity || 'day';
+  const series = chartPanel(
+    t('chart.series.title.' + period),
+    t('chart.series.note.' + period),
+    // Its y axis is minutes, so more skills only add segments to bars that
+    // already have room — this one does not grow.
+    320
+  );
+  view.append(series.panel);
+  if (hasChart) buildSeriesChart(series.canvas, report.series, report.skills);
+
+  const timeline = chartPanel(
+    t('chart.timeline.title'),
+    t('chart.timeline.note'),
+    heightForRows(rows, TIMELINE_ROW_PX)
+  );
+  view.append(timeline.panel);
+  if (hasChart) buildTimelineChart(timeline.canvas, report.skills, report.runs);
+
+  view.append(footer(full));
+}
+
+/** A failed load must say so; a blank page explains nothing. */
+function renderError(err) {
+  view.replaceChildren();
+  view.append(
+    el('section', { class: 'panel' }, [
+      el('h2', { text: t('error.title') }),
+      el('p', { class: 'panel-note', text: String((err && err.message) || err) }),
+    ])
+  );
+}
+
+/** Charts read CSS variables when constructed, so a rebuild must drop the old ones. */
+function destroyCharts() {
+  for (const chart of liveCharts) chart.destroy();
+  liveCharts.clear();
+}
+
+/** The last report fetched, so view-only controls can redraw without a request. */
+let current = null;
+
+function render() {
+  if (!current) return;
+  destroyCharts();
+  renderReport(current);
+}
+
+function load(refresh) {
+  destroyCharts();
+  return api('/api/report?' + reportQuery(refresh))
+    .then((report) => {
+      current = report;
+      renderReport(report);
+    })
+    .catch(renderError);
+}
+
+void load();