gloomberb 0.10.4 → 0.11.0

package/src/plugins/builtin/polls/client.ts

@@ -0,0 +1,57 @@
+import { createThrottledFetch } from "../../../utils/throttled-fetch";
+import { httpFetch } from "../../../utils/http-transport";
+import type { VoteHubPoll } from "./types";
+
+const BASE_URL = "https://api.votehub.com";
+
+const VOTEHUB_FETCH = createThrottledFetch({
+  requestsPerMinute: 30,
+  maxRetries: 2,
+  timeoutMs: 12_000,
+  backoffBaseMs: 500,
+  dedupeGetRequests: true,
+  defaultHeaders: {
+    Accept: "application/json",
+    "User-Agent": "gloomberb-polls",
+  },
+  transport: httpFetch,
+});
+
+export function parseVoteHubPollsPayload(body: unknown): VoteHubPoll[] {
+  if (Array.isArray(body)) return body.filter(isVoteHubPoll);
+  if (body && typeof body === "object" && Array.isArray((body as { polls?: unknown }).polls)) {
+    return (body as { polls: unknown[] }).polls.filter(isVoteHubPoll);
+  }
+  return [];
+}
+
+function isVoteHubPoll(value: unknown): value is VoteHubPoll {
+  if (!value || typeof value !== "object") return false;
+  const poll = value as Record<string, unknown>;
+  return typeof poll.id === "string" && typeof poll.pollster === "string" && typeof poll.subject === "string";
+}
+
+function buildUrl(path: string, params?: Record<string, string | undefined>): string {
+  const url = new URL(`${BASE_URL}${path}`);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value) url.searchParams.set(key, value);
+    }
+  }
+  return url.toString();
+}
+
+export async function fetchVoteHubPolls(params?: {
+  pollType?: string;
+  subject?: string;
+}): Promise<VoteHubPoll[]> {
+  const url = buildUrl("/polls", {
+    poll_type: params?.pollType,
+    subject: params?.subject,
+  });
+  const response = await VOTEHUB_FETCH.fetch(url);
+  if (!response.ok) {
+    throw new Error(`VoteHub request failed (${response.status})`);
+  }
+  return parseVoteHubPollsPayload(await response.json());
+}

package/src/plugins/builtin/polls/hooks.ts

@@ -0,0 +1,20 @@
+interface StackSortPreference<C extends string> {
+  columnId: C;
+  direction: "asc" | "desc";
+}
+
+/**
+ * Cycles a table's sort preference when a header is clicked: toggles direction
+ * on the active column, otherwise switches to the new column at its default
+ * direction.
+ */
+export function nextStackSortPreference<C extends string>(
+  current: StackSortPreference<C>,
+  columnId: C,
+  defaultDirection: "asc" | "desc" = "desc",
+): StackSortPreference<C> {
+  if (current.columnId === columnId) {
+    return { columnId, direction: current.direction === "asc" ? "desc" : "asc" };
+  }
+  return { columnId, direction: defaultDirection };
+}

package/src/plugins/builtin/polls/index.tsx

@@ -0,0 +1,35 @@
+import type { GloomPlugin } from "../../../types/plugin";
+import { PollsPane } from "./pane";
+import { POLLS_PANE_ID, POLLS_PLUGIN_ID } from "./types";
+
+export const pollsPlugin: GloomPlugin = {
+  id: POLLS_PLUGIN_ID,
+  name: "Polls",
+  version: "1.0.0",
+  description: "Political polls from VoteHub (CC BY 4.0)",
+  toggleable: true,
+
+  panes: [
+    {
+      id: POLLS_PANE_ID,
+      name: "Polls",
+      icon: "P",
+      component: PollsPane,
+      defaultPosition: "right",
+      defaultMode: "floating",
+      defaultFloatingSize: { width: 100, height: 32 },
+    },
+  ],
+
+  paneTemplates: [
+    {
+      id: "polls-pane",
+      paneId: POLLS_PANE_ID,
+      label: "Polls",
+      description: "Browse VoteHub political polls by type — approval, favorability, generic ballot, Senate, governor, House — with trend charts, pollster breakdowns, search, and source links.",
+      keywords: ["polls", "votehub", "approval", "favorability", "generic", "ballot", "senate", "governor"],
+      shortcut: { prefix: "POLL" },
+      createInstance: () => ({ placement: "floating" }),
+    },
+  ],
+};

package/src/plugins/builtin/polls/normalize.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, test } from "bun:test";
+import { parseVoteHubPollsPayload } from "./client";
+import {
+  computeMarginOfError,
+  computeMovingAverage,
+  computePollAverages,
+  computePollsterAverages,
+  computePollTrend,
+  filterPollRows,
+  normalizeVoteHubPoll,
+  parseSampleSize,
+  populationLabel,
+  sortPollRows,
+  summarizeAnswers,
+} from "./normalize";
+import type { PollRow, VoteHubPoll } from "./types";
+
+function makePoll(overrides: Partial<VoteHubPoll> = {}): VoteHubPoll {
+  return {
+    id: "p1",
+    poll_type: "approval",
+    sample_size: 1000,
+    population: "rv",
+    url: null,
+    created_at: null,
+    start_date: "2026-01-01",
+    end_date: "2026-01-03",
+    pollster: "Test Pollster",
+    answers: [
+      { choice: "Approve", pct: 45 },
+      { choice: "Disapprove", pct: 50 },
+    ],
+    seat_name: null,
+    sponsors: [],
+    internal: false,
+    partisan: null,
+    subject: "Donald Trump",
+    ...overrides,
+  };
+}
+
+describe("VoteHub normalize", () => {
+  test("accepts a bare poll array or a { polls } envelope", () => {
+    const poll = makePoll();
+    expect(parseVoteHubPollsPayload([poll])).toHaveLength(1);
+    expect(parseVoteHubPollsPayload({ polls: [poll] })).toHaveLength(1);
+    expect(parseVoteHubPollsPayload({ data: [poll] })).toHaveLength(0);
+  });
+
+  test("summarizes a two-way result and lead", () => {
+    const summary = summarizeAnswers([
+      { choice: "Disapprove", pct: 51 },
+      { choice: "Approve", pct: 44 },
+    ]);
+    expect(summary.leadChoice).toBe("Disapprove");
+    expect(summary.lead).toBeCloseTo(7);
+    expect(summary.result).toContain("Disapprove");
+    expect(summary.result).toContain("Approve");
+  });
+
+  test("maps wire fields onto list rows including margin of error", () => {
+    const row = normalizeVoteHubPoll(makePoll({
+      poll_type: "generic-ballot",
+      sample_size: "1,500",
+      population: "lv",
+      answers: [
+        { choice: "Dem", pct: 44.4 },
+        { choice: "Rep", pct: 48.4 },
+      ],
+    }));
+    expect(row.pollTypeLabel).toBe("Generic");
+    expect(row.population).toBe("Likely");
+    expect(row.sampleSize).toBe(1500);
+    expect(row.leadChoice).toBe("Rep");
+    expect(row.lead).toBeCloseTo(4);
+    expect(row.marginOfError).not.toBeNull();
+    expect(parseSampleSize("800")).toBe(800);
+    expect(populationLabel("rv")).toBe("Reg");
+  });
+
+  test("sorts poll rows by date, pollster, or lead", () => {
+    const older = normalizeVoteHubPoll(makePoll({
+      id: "old",
+      start_date: "2026-07-01",
+      end_date: "2026-07-02",
+      pollster: "YouGov",
+      answers: [{ choice: "Approve", pct: 40 }, { choice: "Disapprove", pct: 50 }],
+    }));
+    const newer = normalizeVoteHubPoll(makePoll({
+      id: "new",
+      start_date: "2026-08-01",
+      end_date: "2026-08-10",
+      pollster: "Emerson",
+      answers: [{ choice: "Approve", pct: 55 }, { choice: "Disapprove", pct: 40 }],
+    }));
+
+    expect(sortPollRows([older, newer]).map((row) => row.id)).toEqual(["new", "old"]);
+    expect(sortPollRows([older, newer], { columnId: "pollster", direction: "asc" }).map((row) => row.id))
+      .toEqual(["new", "old"]);
+    expect(sortPollRows([older, newer], { columnId: "result", direction: "desc" }).map((row) => row.id))
+      .toEqual(["new", "old"]);
+  });
+});
+
+describe("computeMarginOfError", () => {
+  test("returns null for missing or invalid sample sizes", () => {
+    expect(computeMarginOfError(null)).toBeNull();
+    expect(computeMarginOfError(0)).toBeNull();
+    expect(computeMarginOfError(-5)).toBeNull();
+  });
+
+  test("computes MoE decreasing with larger samples", () => {
+    const small = computeMarginOfError(100);
+    const large = computeMarginOfError(10_000);
+    expect(small).not.toBeNull();
+    expect(large).not.toBeNull();
+    expect(small!).toBeGreaterThan(large!);
+    // 0.98 / sqrt(1000) ≈ 3.1
+    expect(computeMarginOfError(1000)).toBeCloseTo(3.1, 0);
+  });
+});
+
+describe("filterPollRows", () => {
+  const rows = [
+    normalizeVoteHubPoll(makePoll({ id: "a", subject: "Donald Trump", pollster: "Ipsos" })),
+    normalizeVoteHubPoll(makePoll({ id: "b", subject: "Congress", pollster: "Gallup" })),
+    normalizeVoteHubPoll(makePoll({ id: "c", subject: "Donald Trump", pollster: "Emerson" })),
+  ];
+
+  test("returns all rows for empty query", () => {
+    expect(filterPollRows(rows, "")).toHaveLength(3);
+    expect(filterPollRows(rows, "   ")).toHaveLength(3);
+  });
+
+  test("filters by subject case-insensitively", () => {
+    expect(filterPollRows(rows, "trump").map((r) => r.id)).toEqual(["a", "c"]);
+  });
+
+  test("filters by pollster case-insensitively", () => {
+    expect(filterPollRows(rows, "gallup").map((r) => r.id)).toEqual(["b"]);
+  });
+});
+
+describe("computePollTrend", () => {
+  const rows = [
+    normalizeVoteHubPoll(makePoll({ id: "t1", end_date: "2026-01-10", subject: "Donald Trump", answers: [{ choice: "Approve", pct: 45 }, { choice: "Disapprove", pct: 50 }] })),
+    normalizeVoteHubPoll(makePoll({ id: "t2", end_date: "2026-02-10", subject: "Donald Trump", answers: [{ choice: "Approve", pct: 42 }, { choice: "Disapprove", pct: 53 }] })),
+    normalizeVoteHubPoll(makePoll({ id: "t3", end_date: "2026-03-10", subject: "Congress", answers: [{ choice: "Approve", pct: 20 }, { choice: "Disapprove", pct: 70 }] })),
+  ];
+
+  test("collects sorted time series for matching subject and choice", () => {
+    const trend = computePollTrend(rows, "Donald Trump", "Approve");
+    expect(trend).toHaveLength(2);
+    expect(trend[0]!.date).toBe("2026-01-10");
+    expect(trend[1]!.date).toBe("2026-02-10");
+    expect(trend[0]!.value).toBe(45);
+  });
+
+  test("returns empty for non-matching subject", () => {
+    expect(computePollTrend(rows, "Unknown", "Approve")).toHaveLength(0);
+  });
+});
+
+describe("computeMovingAverage", () => {
+  const points = [
+    { date: "2026-01-01", value: 40, pollster: "A" },
+    { date: "2026-01-02", value: 50, pollster: "B" },
+    { date: "2026-01-03", value: 60, pollster: "C" },
+    { date: "2026-01-04", value: 30, pollster: "D" },
+  ];
+
+  test("computes rolling mean with the given window", () => {
+    const ma = computeMovingAverage(points, 2);
+    expect(ma).toHaveLength(3);
+    expect(ma[0]!.value).toBe(45); // (40+50)/2
+    expect(ma[1]!.value).toBe(55); // (50+60)/2
+    expect(ma[2]!.value).toBe(45); // (60+30)/2
+  });
+
+  test("returns empty when fewer points than window", () => {
+    expect(computeMovingAverage(points, 5)).toHaveLength(0);
+  });
+});
+
+describe("computePollsterAverages", () => {
+  const rows: PollRow[] = [
+    normalizeVoteHubPoll(makePoll({ id: "pa1", pollster: "Ipsos", sample_size: 1000, subject: "Donald Trump", answers: [{ choice: "Approve", pct: 45 }, { choice: "Disapprove", pct: 50 }] })),
+    normalizeVoteHubPoll(makePoll({ id: "pa2", pollster: "Ipsos", sample_size: 2000, subject: "Donald Trump", answers: [{ choice: "Approve", pct: 48 }, { choice: "Disapprove", pct: 47 }] })),
+    normalizeVoteHubPoll(makePoll({ id: "pa3", pollster: "Gallup", sample_size: 1000, subject: "Donald Trump", answers: [{ choice: "Approve", pct: 50 }, { choice: "Disapprove", pct: 45 }] })),
+  ];
+
+  test("groups by pollster with sample-weighted average", () => {
+    const result = computePollsterAverages(rows, "Donald Trump", "Approve");
+    expect(result).toHaveLength(2);
+    const ipsos = result.find((r) => r.pollster === "Ipsos")!;
+    expect(ipsos.count).toBe(2);
+    expect(ipsos.totalSample).toBe(3000);
+    // (45*1000 + 48*2000) / 3000 = 147000/3000 = 47
+    expect(ipsos.avgPct).toBeCloseTo(47, 0);
+  });
+
+  test("sorts by poll count descending", () => {
+    const result = computePollsterAverages(rows, "Donald Trump", "Approve");
+    expect(result[0]!.count).toBeGreaterThanOrEqual(result[1]!.count);
+  });
+});
+
+describe("computePollAverages", () => {
+  const rows: PollRow[] = [
+    normalizeVoteHubPoll(makePoll({ id: "avg1", end_date: "2026-03-01", pollster: "Ipsos", sample_size: 1000, subject: "Donald Trump", answers: [{ choice: "Approve", pct: 44 }, { choice: "Disapprove", pct: 50 }] })),
+    normalizeVoteHubPoll(makePoll({ id: "avg2", end_date: "2026-02-01", pollster: "Gallup", sample_size: 2000, subject: "Donald Trump", answers: [{ choice: "Approve", pct: 46 }, { choice: "Disapprove", pct: 48 }] })),
+  ];
+
+  test("computes sample-weighted average per choice across recent polls", () => {
+    const result = computePollAverages(rows, "Donald Trump", 10);
+    expect(result).toHaveLength(2);
+    expect(result[0]!.choice).toBe("Disapprove");
+    // Disapprove: (50*1000 + 48*2000) / 3000 = 146000/3000 ≈ 48.67
+    expect(result[0]!.avgPct).toBeCloseTo(48.67, 0);
+    expect(result[0]!.pollCount).toBe(2);
+  });
+
+  test("respects recentCount limit", () => {
+    const result = computePollAverages(rows, "Donald Trump", 1);
+    // Only the most recent poll (avg1, end_date 2026-03-01)
+    const approve = result.find((r) => r.choice === "Approve")!;
+    expect(approve.pollCount).toBe(1);
+    expect(approve.avgPct).toBe(44);
+  });
+});

package/src/plugins/builtin/polls/normalize.ts

@@ -0,0 +1,319 @@
+import type {
+  PollAverageSummary,
+  PollRow,
+  PollTrendPoint,
+  PollsterAverage,
+  VoteHubPoll,
+  VoteHubPollAnswer,
+} from "./types";
+
+const POLL_TYPE_LABELS: Record<string, string> = {
+  approval: "Approval",
+  favorability: "Favorability",
+  "generic-ballot": "Generic",
+  "us-senator": "Senate",
+  governor: "Governor",
+  "us-representative": "House",
+  mayor: "Mayor",
+  "attorney-general": "AG",
+  "presidential-primary": "Primary",
+  "proposition-50": "Prop",
+};
+
+/** Readable sample populations; "A"/"RV"/"LV" meant nothing without a legend. */
+const POPULATION_LABELS: Record<string, string> = {
+  a: "Adults",
+  rv: "Reg",
+  lv: "Likely",
+};
+
+export function pollTypeLabel(pollType: string): string {
+  return POLL_TYPE_LABELS[pollType] ?? pollType.replace(/-/g, " ");
+}
+
+export function populationLabel(population: string | null | undefined): string {
+  if (!population) return "—";
+  return POPULATION_LABELS[population.toLowerCase()] ?? population.toUpperCase();
+}
+
+export function parseSampleSize(value: number | string | null | undefined): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Number(value.replace(/,/g, ""));
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+/**
+ * Approximate 95% confidence margin of error for a proportion at 50/50,
+ * derived from sample size: MoE ≈ 0.98 / sqrt(n).
+ * Returns null when sample size is missing or too small to be meaningful.
+ */
+export function computeMarginOfError(sampleSize: number | null): number | null {
+  if (sampleSize == null || sampleSize < 1) return null;
+  const moe = (0.98 / Math.sqrt(sampleSize)) * 100;
+  return Number.isFinite(moe) ? Math.round(moe * 10) / 10 : null;
+}
+
+export function formatPollDate(value: string | null | undefined): string {
+  if (!value) return "—";
+  const date = new Date(`${value}T00:00:00Z`);
+  if (!Number.isFinite(date.getTime())) return value;
+  return date.toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
+}
+
+function sortedAnswers(answers: VoteHubPollAnswer[] | undefined): VoteHubPollAnswer[] {
+  return [...(answers ?? [])]
+    .filter((answer) => typeof answer.choice === "string" && Number.isFinite(answer.pct))
+    .sort((left, right) => right.pct - left.pct);
+}
+
+export function summarizeAnswers(answers: VoteHubPollAnswer[] | undefined): {
+  result: string;
+  lead: number | null;
+  leadChoice: string | null;
+} {
+  const ranked = sortedAnswers(answers);
+  const first = ranked[0];
+  const second = ranked[1];
+  if (!first) return { result: "—", lead: null, leadChoice: null };
+  if (!second) {
+    return {
+      result: `${shortChoice(first.choice)} ${formatPct(first.pct)}`,
+      lead: first.pct,
+      leadChoice: first.choice,
+    };
+  }
+  const lead = first.pct - second.pct;
+  return {
+    result: `${shortChoice(first.choice)} ${formatPct(first.pct)}  ${shortChoice(second.choice)} ${formatPct(second.pct)}`,
+    lead,
+    leadChoice: first.choice,
+  };
+}
+
+function shortChoice(choice: string): string {
+  const trimmed = choice.trim();
+  if (trimmed.length <= 10) return trimmed;
+  return trimmed.slice(0, 9);
+}
+
+function formatPct(value: number): string {
+  return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+
+export function normalizeVoteHubPoll(poll: VoteHubPoll): PollRow {
+  const summary = summarizeAnswers(poll.answers);
+  const sampleSize = parseSampleSize(poll.sample_size);
+  return {
+    id: poll.id,
+    subject: poll.subject,
+    pollType: poll.poll_type,
+    pollTypeLabel: pollTypeLabel(poll.poll_type),
+    pollster: poll.pollster,
+    population: populationLabel(poll.population),
+    sampleSize,
+    marginOfError: computeMarginOfError(sampleSize),
+    startDate: poll.start_date,
+    endDate: poll.end_date,
+    result: summary.result,
+    lead: summary.lead,
+    leadChoice: summary.leadChoice,
+    url: poll.url,
+    sponsors: Array.isArray(poll.sponsors) ? poll.sponsors.filter((sponsor) => typeof sponsor === "string") : [],
+    partisan: typeof poll.partisan === "string" ? poll.partisan : null,
+    internal: poll.internal === true,
+    answers: sortedAnswers(poll.answers),
+  };
+}
+
+export type PollSortColumnId = "date" | "subject" | "pollster" | "pop" | "result";
+
+export interface PollSortPreference {
+  columnId: PollSortColumnId;
+  direction: "asc" | "desc";
+}
+
+export const DEFAULT_POLL_SORT: PollSortPreference = { columnId: "date", direction: "desc" };
+
+export function comparePollRows(
+  left: PollRow,
+  right: PollRow,
+  columnId: PollSortColumnId,
+): number {
+  switch (columnId) {
+    case "date":
+      return dateValue(left.endDate ?? left.startDate) - dateValue(right.endDate ?? right.startDate);
+    case "subject":
+      return left.subject.localeCompare(right.subject);
+    case "pollster":
+      return left.pollster.localeCompare(right.pollster);
+    case "pop":
+      return left.population.localeCompare(right.population);
+    case "result":
+      return (left.lead ?? Number.NEGATIVE_INFINITY) - (right.lead ?? Number.NEGATIVE_INFINITY);
+  }
+}
+
+export function sortPollRows(
+  rows: PollRow[],
+  preference: PollSortPreference = DEFAULT_POLL_SORT,
+): PollRow[] {
+  const sign = preference.direction === "asc" ? 1 : -1;
+  return [...rows].sort((left, right) => {
+    const primary = comparePollRows(left, right, preference.columnId);
+    if (primary !== 0) return sign * primary;
+    return left.subject.localeCompare(right.subject);
+  });
+}
+
+function dateValue(value: string | null): number {
+  if (!value) return 0;
+  const time = new Date(`${value}T00:00:00Z`).getTime();
+  return Number.isFinite(time) ? time : 0;
+}
+
+/**
+ * Case-insensitive substring filter across subject, pollster, and seat name.
+ * Returns the original array when the query is empty.
+ */
+export function filterPollRows(rows: PollRow[], query: string): PollRow[] {
+  const trimmed = query.trim().toLowerCase();
+  if (!trimmed) return rows;
+  return rows.filter((row) =>
+    row.subject.toLowerCase().includes(trimmed) ||
+    row.pollster.toLowerCase().includes(trimmed) ||
+    row.pollTypeLabel.toLowerCase().includes(trimmed),
+  );
+}
+
+/**
+ * Collect a time series of percentage values for a specific choice across all
+ * polls sharing the same subject. Points are sorted chronologically by end date.
+ */
+export function computePollTrend(
+  rows: PollRow[],
+  subject: string,
+  choice: string,
+): PollTrendPoint[] {
+  const target = choice.toLowerCase();
+  const points: PollTrendPoint[] = [];
+  for (const row of rows) {
+    if (row.subject !== subject) continue;
+    const answer = row.answers.find((a) => a.choice.toLowerCase() === target);
+    if (!answer) continue;
+    const date = row.endDate ?? row.startDate;
+    if (!date) continue;
+    points.push({ date, value: answer.pct, pollster: row.pollster });
+  }
+  return points.sort((a, b) => dateValue(a.date) - dateValue(b.date));
+}
+
+/**
+ * Simple moving average over a sorted trend series. Each output point is the
+ * mean of the current and preceding `window - 1` values. Returns an empty
+ * array when there are fewer than `window` points.
+ */
+export function computeMovingAverage(
+  points: PollTrendPoint[],
+  window: number,
+): Array<{ date: string; value: number }> {
+  if (window < 1 || points.length < window) return [];
+  const result: Array<{ date: string; value: number }> = [];
+  for (let i = window - 1; i < points.length; i++) {
+    let sum = 0;
+    for (let j = i - window + 1; j <= i; j++) {
+      sum += points[j]!.value;
+    }
+    result.push({ date: points[i]!.date, value: sum / window });
+  }
+  return result;
+}
+
+/**
+ * Group polls by pollster for a given subject and compute the sample-size-
+ * weighted average of the leading choice's percentage, poll count, total
+ * sample, and most recent end date. Sorted by poll count descending.
+ */
+export function computePollsterAverages(
+  rows: PollRow[],
+  subject: string,
+  choice: string | null,
+): PollsterAverage[] {
+  const target = choice?.toLowerCase();
+  const byPollster = new Map<string, { sum: number; weight: number; count: number; lastDate: string | null }>();
+  for (const row of rows) {
+    if (row.subject !== subject) continue;
+    const answer = target
+      ? row.answers.find((a) => a.choice.toLowerCase() === target)
+      : row.answers[0];
+    if (!answer) continue;
+    const weight = row.sampleSize ?? 0;
+    const entry = byPollster.get(row.pollster);
+    if (entry) {
+      entry.sum += answer.pct * weight;
+      entry.weight += weight;
+      entry.count += 1;
+      const d = row.endDate ?? row.startDate;
+      if (d && (!entry.lastDate || dateValue(d) > dateValue(entry.lastDate))) {
+        entry.lastDate = d;
+      }
+    } else {
+      byPollster.set(row.pollster, {
+        sum: answer.pct * weight,
+        weight,
+        count: 1,
+        lastDate: row.endDate ?? row.startDate,
+      });
+    }
+  }
+  return [...byPollster.entries()]
+    .map(([pollster, entry]) => ({
+      pollster,
+      count: entry.count,
+      avgPct: entry.weight > 0 ? entry.sum / entry.weight : entry.sum / entry.count,
+      totalSample: entry.weight,
+      lastDate: entry.lastDate,
+    }))
+    .sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Compute a sample-size-weighted average for each choice across recent polls
+ * sharing a subject. `recentCount` limits to the most recent N polls by end
+ * date. Returns summaries sorted by average percentage descending.
+ */
+export function computePollAverages(
+  rows: PollRow[],
+  subject: string,
+  recentCount: number,
+): PollAverageSummary[] {
+  const matching = rows
+    .filter((row) => row.subject === subject)
+    .sort((a, b) => dateValue(b.endDate ?? b.startDate) - dateValue(a.endDate ?? a.startDate))
+    .slice(0, Math.max(1, recentCount));
+
+  const byChoice = new Map<string, { sum: number; weight: number; count: number }>();
+  for (const row of matching) {
+    for (const answer of row.answers) {
+      const weight = row.sampleSize ?? 1;
+      const entry = byChoice.get(answer.choice);
+      if (entry) {
+        entry.sum += answer.pct * weight;
+        entry.weight += weight;
+        entry.count += 1;
+      } else {
+        byChoice.set(answer.choice, { sum: answer.pct * weight, weight, count: 1 });
+      }
+    }
+  }
+  return [...byChoice.entries()]
+    .map(([choice, entry]) => ({
+      choice,
+      avgPct: entry.weight > 0 ? entry.sum / entry.weight : entry.sum / entry.count,
+      pollCount: entry.count,
+      totalSample: entry.weight,
+    }))
+    .sort((a, b) => b.avgPct - a.avgPct);
+}