npm - beadcyte - Versions diffs - 0.4.0 - Mend

beadcyte 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (108) hide show

package/CHANGELOG.md +73 -0
package/LICENSE +661 -0
package/README.md +386 -0
package/THIRD_PARTY_NOTICES.md +56 -0
package/bin/beadcyte.mjs +60 -0
package/package.json +77 -0
package/src/changelog-cli.mjs +105 -0
package/src/changelog.mjs +196 -0
package/src/cli.mjs +577 -0
package/src/estimator.mjs +314 -0
package/src/format.mjs +22 -0
package/src/history-walk.mjs +170 -0
package/src/index.mjs +5 -0
package/src/mutate.mjs +193 -0
package/src/projects.mjs +120 -0
package/src/provenance.mjs +75 -0
package/src/review-hours.mjs +117 -0
package/src/roster-path.mjs +24 -0
package/src/scheduler.mjs +424 -0
package/src/serve.mjs +411 -0
package/src/server-state.mjs +105 -0
package/src/ship.mjs +178 -0
package/src/stage-waits.mjs +69 -0
package/src/start.mjs +111 -0
package/src/stop.mjs +66 -0
package/src/velocity.mjs +209 -0
package/src/web/App.vue +691 -0
package/src/web/app.css +54 -0
package/src/web/assets/favicon.svg +12 -0
package/src/web/avatar.ts +53 -0
package/src/web/bead-detail.ts +240 -0
package/src/web/changelog-view.ts +41 -0
package/src/web/components/BeadDrawer.vue +1883 -0
package/src/web/components/BeadSubGraph.vue +326 -0
package/src/web/components/BeadSubGraphOverlay.vue +192 -0
package/src/web/components/BeadTooltip.vue +516 -0
package/src/web/components/BeadcyteMark.vue +64 -0
package/src/web/components/BeadsGantt.vue +2125 -0
package/src/web/components/BeadsGrid.vue +468 -0
package/src/web/components/BeadsIncytes.vue +567 -0
package/src/web/components/BeadsMine.vue +325 -0
package/src/web/components/BeadsTable.vue +335 -0
package/src/web/components/ChangelogOverlay.vue +198 -0
package/src/web/components/ContextMenu.vue +386 -0
package/src/web/components/ControlsPanel.vue +476 -0
package/src/web/components/CostTrend.vue +206 -0
package/src/web/components/FilterPopover.vue +245 -0
package/src/web/components/GroupProgress.vue +274 -0
package/src/web/components/LoadMeter.vue +144 -0
package/src/web/components/MineRow.vue +28 -0
package/src/web/components/OptionsMenu.vue +825 -0
package/src/web/components/PriorityChip.vue +105 -0
package/src/web/components/ScoreStrip.vue +131 -0
package/src/web/components/SearchPalette.vue +210 -0
package/src/web/components/ShipTrend.vue +510 -0
package/src/web/components/ShortcutsOverlay.vue +164 -0
package/src/web/components/Term.vue +177 -0
package/src/web/components/Toast.vue +50 -0
package/src/web/components/TriageMeters.vue +426 -0
package/src/web/components/TypeChip.vue +96 -0
package/src/web/components/Walkthrough.vue +209 -0
package/src/web/components/WhatIfPanel.vue +206 -0
package/src/web/components/WipBullets.vue +191 -0
package/src/web/components/filter-option.ts +9 -0
package/src/web/composables/url-codec.ts +136 -0
package/src/web/composables/useBeadTooltip.ts +148 -0
package/src/web/composables/useKeyboard.ts +97 -0
package/src/web/composables/useLiveRefresh.ts +69 -0
package/src/web/composables/useTheme.ts +125 -0
package/src/web/composables/useUrlState.ts +208 -0
package/src/web/controls-scope.ts +83 -0
package/src/web/cost.ts +251 -0
package/src/web/dep-headings.ts +62 -0
package/src/web/economics.ts +440 -0
package/src/web/env.d.ts +85 -0
package/src/web/frontier.ts +208 -0
package/src/web/gantt-viewport.ts +99 -0
package/src/web/highlights.ts +124 -0
package/src/web/index.html +46 -0
package/src/web/insights.ts +107 -0
package/src/web/keybindings.ts +200 -0
package/src/web/load-meter.ts +72 -0
package/src/web/main.ts +20 -0
package/src/web/markdown.ts +14 -0
package/src/web/mine.ts +137 -0
package/src/web/mutations.ts +21 -0
package/src/web/person.ts +102 -0
package/src/web/projects-text.ts +15 -0
package/src/web/projects.ts +188 -0
package/src/web/refresh.ts +47 -0
package/src/web/search.ts +50 -0
package/src/web/shortcuts.ts +113 -0
package/src/web/status-filter.ts +48 -0
package/src/web/store.ts +1378 -0
package/src/web/style-audit.mjs +346 -0
package/src/web/styles-alt.css +111 -0
package/src/web/styles-ported.css +270 -0
package/src/web/subgraph.ts +362 -0
package/src/web/table.ts +201 -0
package/src/web/theme.ts +88 -0
package/src/web/tokens.css +168 -0
package/src/web/triage.ts +914 -0
package/src/web/view-model.ts +717 -0
package/src/web/walkthrough.ts +133 -0
package/src/web/watchlist.ts +47 -0
package/src/web/whatif.ts +291 -0
package/src/web/window.ts +73 -0
package/src/web/wip.ts +83 -0

package/src/web/composables/useTheme.ts ADDED Viewed

@@ -0,0 +1,125 @@
+// useTheme.ts — applies the theme mode and style family to <html>.
+//
+// theme.ts owns what a valid preference is; this owns the reactive state,
+// the root attributes and persistence. Module-level singletons so every
+// consumer shares one source of truth.
+import { computed, readonly, ref } from "vue";
+import {
+  STYLE_STORAGE_KEY,
+  THEME_STORAGE_KEY,
+  parseStyleName,
+  parseThemeMode,
+  resolveIsDark,
+  nextThemeMode,
+  type StyleName,
+  type ThemeMode,
+} from "../theme";
+/**
+ * Reading localStorage THROWS when storage is blocked (not just returns
+ * null), and this runs at module load — so an unguarded read takes the whole
+ * app down to a blank page rather than merely losing a preference.
+ */
+function readStored(key: string): string | null {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function writeStored(key: string, value: string) {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+    // Private mode or a full quota. The choice still applies for this
+    // session, it just won't survive a reload.
+  }
+}
+// ?theme= overrides the stored mode for one visit without persisting, the
+// same way ?fx= overrides the style. Useful for sharing or inspecting a
+// specific appearance, and the only way to reach a mode the OS isn't in
+// without changing OS settings.
+function detectMode(): ThemeMode {
+  const stored = parseThemeMode(readStored(THEME_STORAGE_KEY));
+  if (typeof location === "undefined") return stored;
+  const q = new URLSearchParams(location.search).get("theme");
+  return q ? parseThemeMode(q) : stored;
+}
+const mode = ref<ThemeMode>(detectMode());
+// ?fx= overrides the stored style for one visit without persisting, so a
+// style can be shared or tried by link.
+//
+// DECISION (bp-67g.14): appearance is an override, not URL state. ?view=,
+// ?group= and the filters round-trip — they describe what you are looking
+// AT, so a link should reproduce it. A theme describes how you like to look
+// at it, which is a property of the reader, not the thing. Writing it into
+// the URL would mean every shared link imposed the sender's taste on the
+// recipient. So it persists per browser and the query param is a one-visit
+// override for sharing or inspecting a specific appearance.
+function detectStyle(): StyleName {
+  const stored = parseStyleName(readStored(STYLE_STORAGE_KEY));
+  if (typeof location === "undefined") return stored;
+  const fx = new URLSearchParams(location.search).get("fx");
+  return fx ? parseStyleName(fx) : stored;
+}
+const style = ref<StyleName>(detectStyle());
+const mql =
+  typeof window !== "undefined" && window.matchMedia
+    ? window.matchMedia("(prefers-color-scheme: dark)")
+    : null;
+const prefersDark = ref(mql ? mql.matches : true);
+mql?.addEventListener("change", (e) => (prefersDark.value = e.matches));
+/** What's on screen right now, with 'system' already resolved. */
+const isDark = computed(() => resolveIsDark(mode.value, prefersDark.value));
+function applyMode(value: ThemeMode) {
+  const root = document.documentElement;
+  // Absent attribute is what lets color-scheme fall through to the OS, so
+  // 'system' removes rather than writes.
+  if (value === "system") root.removeAttribute("data-theme");
+  else root.setAttribute("data-theme", value);
+}
+function applyStyle(value: StyleName) {
+  const root = document.documentElement;
+  if (value === "default") root.removeAttribute("data-style");
+  else root.setAttribute("data-style", value);
+}
+export function useTheme() {
+  return {
+    mode: readonly(mode),
+    style: readonly(style),
+    isDark,
+    setMode(value: ThemeMode) {
+      mode.value = value;
+      writeStored(THEME_STORAGE_KEY, value);
+      applyMode(value);
+    },
+    cycleMode() {
+      this.setMode(nextThemeMode(mode.value));
+    },
+    setStyle(value: StyleName) {
+      style.value = value;
+      writeStored(STYLE_STORAGE_KEY, value);
+      applyStyle(value);
+    },
+    /** Push the loaded preferences onto <html>. Call once at startup. */
+    init() {
+      applyMode(mode.value);
+      applyStyle(style.value);
+    },
+  };
+}

package/src/web/composables/useUrlState.ts ADDED Viewed

@@ -0,0 +1,208 @@
+import { watch } from "vue";
+import { useBeadsStore } from "../store";
+import {
+  parseGroupBy,
+  parseView,
+  serializeArray,
+  deserializeStrings,
+  deserializeNumbers,
+  serializeDate,
+  parseDate,
+  legacyHiddenStatuses,
+} from "./url-codec";
+/**
+ * Hydrate the store from the URL query string on mount.
+ */
+export function useUrlState() {
+  const store = useBeadsStore();
+  // Hydrate from URL on initial load
+  function hydrateFromUrl() {
+    const urlParams = new URLSearchParams(window.location.search);
+    // Handle groupBy. parseGroupBy returns null for anything unrecognised so
+    // the store keeps its default rather than being cast into a bad mode.
+    const groupBy = parseGroupBy(urlParams.get("group"));
+    if (groupBy) store.setGroupBy(groupBy);
+    // Handle view. Unlike the others this always resolves — a missing or
+    // unrecognised value means the Gantt.
+    store.setView(parseView(urlParams.get("view")));
+    // Handle filters - types
+    const types = urlParams.get("type");
+    if (types) {
+      store.setFilters({ types: deserializeStrings(types) });
+    }
+    // Handle filters - priorities
+    const priorities = urlParams.get("priority");
+    if (priorities) {
+      store.setFilters({ priorities: deserializeNumbers(priorities) });
+    }
+    // Handle filters - statuses
+    const statuses = urlParams.get("status");
+    if (statuses) {
+      store.setFilters({ statuses: deserializeStrings(statuses) });
+    }
+    // Handle filters - labels
+    const labels = urlParams.get("label");
+    if (labels) {
+      store.setFilters({ labels: deserializeStrings(labels) });
+    }
+    // Handle filters - assignees
+    const assignees = urlParams.get("assignee");
+    if (assignees) {
+      store.setFilters({ assignees: deserializeStrings(assignees) });
+    }
+    // The unblocked term (bp-egy): a flag, on or absent.
+    if (urlParams.get("unblocked") === "1") {
+      store.setFilters({ unblocked: true });
+    }
+    // Current user carried by a shared link. Wins for this load only; the
+    // stored choice is untouched, the same rule ?theme= follows.
+    const me = urlParams.get("me");
+    if (me) store.setUrlUser(me);
+    // The person the incytes view is scoped to (bp-67g.43). Handles are not
+    // private, so a link carrying one is meaningful anywhere the repo is.
+    const who = urlParams.get("who");
+    if (who) store.setWho(who);
+    // Legacy `?showClosed=`/`?includeDeferred=` (pre-bp-67g.40). Both were
+    // separate booleans that silently overrode `?status=`; they are now just
+    // statuses. An explicit `?status=` in the same URL wins outright — it is
+    // the newer, more specific instruction — otherwise these two decide
+    // whether `closed` and `deferred` join the default selection, which
+    // cannot be assembled until the beads say which statuses exist.
+    if (!statuses) {
+      store.setPendingLegacyStatuses(legacyHiddenStatuses(urlParams));
+    }
+    // Handle window - from
+    const from = urlParams.get("from");
+    if (from) {
+      const parsedFrom = parseDate(from);
+      if (parsedFrom) {
+        // Update window from
+        const window = { ...store.window };
+        window.from = parsedFrom;
+        store.setWindow(window);
+      }
+    }
+    // Handle window - to
+    const to = urlParams.get("to");
+    if (to) {
+      const parsedTo = parseDate(to);
+      if (parsedTo) {
+        // Update window to
+        const window = { ...store.window };
+        window.to = parsedTo;
+        store.setWindow(window);
+      }
+    }
+  }
+  // Watch changes to the store and update URL
+  watch(
+    () => ({
+      view: store.view,
+      groupBy: store.groupBy,
+      filters: store.filters,
+      window: store.window,
+      me: store.effectiveUser,
+      who: store.who,
+    }),
+    (newState) => {
+      // Don't update URL for search text or other transient state
+      const ignoreList = new Set(["search"]); // Add any other ignore list fields here
+      const urlParams = new URLSearchParams(window.location.search);
+      // Update view + groupBy in URL
+      urlParams.set("view", newState.view);
+      urlParams.set("group", newState.groupBy);
+      // Update filters in URL
+      if (newState.filters.types) {
+        urlParams.set("type", serializeArray(newState.filters.types));
+      } else {
+        urlParams.delete("type");
+      }
+      if (newState.filters.priorities) {
+        urlParams.set("priority", serializeArray(newState.filters.priorities));
+      } else {
+        urlParams.delete("priority");
+      }
+      if (newState.filters.statuses) {
+        urlParams.set("status", serializeArray(newState.filters.statuses));
+      } else {
+        urlParams.delete("status");
+      }
+      if (newState.filters.labels) {
+        urlParams.set("label", serializeArray(newState.filters.labels));
+      } else {
+        urlParams.delete("label");
+      }
+      if (newState.filters.assignees) {
+        urlParams.set("assignee", serializeArray(newState.filters.assignees));
+      } else {
+        urlParams.delete("assignee");
+      }
+      if (newState.filters.unblocked) {
+        urlParams.set("unblocked", "1");
+      } else {
+        urlParams.delete("unblocked");
+      }
+      if (newState.me) {
+        urlParams.set("me", newState.me);
+      } else {
+        urlParams.delete("me");
+      }
+      if (newState.who) {
+        urlParams.set("who", newState.who);
+      } else {
+        urlParams.delete("who");
+      }
+      // `includeDeferred` and `showClosed` are no longer written. Deleted
+      // rather than left alone, so following an old link and then copying
+      // the address bar does not hand someone a URL carrying params this
+      // build ignores on write and reinterprets on read.
+      urlParams.delete("includeDeferred");
+      urlParams.delete("showClosed");
+      // Handle window - from
+      urlParams.set("from", serializeDate(newState.window.from));
+      // Handle window - to
+      urlParams.set("to", serializeDate(newState.window.to));
+      // Push changes to URL using replaceState (no history entry). The hash
+      // is the drawer's deep link (App.vue): writing the query without it
+      // wiped the bead hash before the payload arrived and the hash handler
+      // ran, so a shared drawer link opened the chart and no drawer.
+      history.replaceState(null, "", `?${urlParams.toString()}${location.hash}`);
+    },
+    { deep: true }
+  );
+  // Initialize from URL
+  hydrateFromUrl();
+}

package/src/web/controls-scope.ts ADDED Viewed

@@ -0,0 +1,83 @@
+// controls-scope.ts — which controls act on which view (bp-67g.36).
+//
+// The controls panel offers the same controls on every view, and on some
+// views most of them do nothing visible. A control that looks live and is
+// inert is worse than one that is absent: the user concludes the data is
+// wrong rather than that the control is irrelevant. This module is the one
+// place that says what each view listens to, derived from what the views
+// actually read:
+//
+//   mine     buildMineModel(store.beads, …): the raw bead list for one person.
+//            Nothing in the panel but the view switch reaches it.
+//   gantt    the filtered, windowed view model, with highlight overlays and
+//            dependency arrows. Everything applies.
+//   grid     the same view model and highlights as cards; it draws no arrows.
+//   table    the same set with the per-group cap lifted, sorted by column
+//            (bp-67g.44). Nothing is painted on it: highlight and arrows are
+//            the Gantt's and the grid's.
+//   incytes  project-wide by design: the trend keeps its own eight-week
+//            window, the roster is static, and Progress groups every bead
+//            (projectGroups). Only group-by changes what it shows.
+//
+// Pure, so the matrix is testable; the panel reads it through
+// controlApplies() and prints scopeNote() once when something is dimmed.
+import type { ViewMode } from "./composables/url-codec";
+export type ControlId =
+  | "groupBy"
+  | "watch"
+  | "mine"
+  | "filters"
+  | "window"
+  | "highlight"
+  | "deps"
+  | "whatif";
+export const CONTROL_IDS: readonly ControlId[] = [
+  "groupBy",
+  "watch",
+  "mine",
+  "filters",
+  "window",
+  "highlight",
+  "deps",
+  "whatif",
+];
+const LIVE: Record<ViewMode, ReadonlySet<ControlId>> = {
+  mine: new Set<ControlId>(),
+  gantt: new Set<ControlId>(CONTROL_IDS),
+  grid: new Set<ControlId>(["groupBy", "watch", "mine", "filters", "window", "highlight", "whatif"]),
+  table: new Set<ControlId>(["groupBy", "watch", "mine", "filters", "window", "whatif"]),
+  incytes: new Set<ControlId>(["groupBy", "whatif"]),
+};
+/** Does this control change what the view shows? */
+export function controlApplies(view: ViewMode, control: ControlId): boolean {
+  return LIVE[view].has(control);
+}
+/** The controls a view does not act on, in panel order. */
+export function inertControls(view: ViewMode): ControlId[] {
+  return CONTROL_IDS.filter((c) => !LIVE[view].has(c));
+}
+/**
+ * One sentence for the panel to print when something is dimmed: what the
+ * view is, and where the dimmed controls do work. Null when nothing is.
+ */
+export function scopeNote(view: ViewMode): string | null {
+  switch (view) {
+    case "mine":
+      return "mine lists one person's work from every bead — the other controls act on the gantt and grid";
+    case "incytes":
+      return "incytes is project-wide — only group by changes it; filters, window and highlight act on the gantt and grid";
+    case "grid":
+      return "dependency arrows are drawn on the gantt only";
+    case "table":
+      return "highlight paints gantt bars and grid cards, and arrows the gantt only — sort a column instead";
+    case "gantt":
+      return null;
+  }
+}

package/src/web/cost.ts ADDED Viewed

@@ -0,0 +1,251 @@
+// cost.ts — the cost trajectory: seat hours and tokens per week, measured
+// behind us and projected ahead (bp-0z5).
+//
+// Beads already carry what they cost: metadata.economics.by_seat (hours per
+// seat, with sessions) and totals (tokens in/out). The ship trend buckets
+// closes into weeks; this buckets the COST of those closes into the same
+// weeks, so the two charts share an axis. Ahead of today, every scheduled
+// bead is given the median cost of comparable shipped work — by issue type,
+// falling back to everything when a type has too few samples — and that cost
+// lands in the week the two-clock schedule says the bead lands.
+//
+// What is measured and what is projected never mix: a week is one or the
+// other (`measured`), the projected weeks are drawn dulled, and the medians
+// that made them are reported with their sample size. Nothing here is a
+// forecast of what a bead WILL cost; it is what comparable work DID cost,
+// placed where the plan puts the bead.
+import type { Bead } from "./store";
+import type { Schedule } from "./view-model";
+import { resolveAssignee } from "./view-model.ts";
+import { buildEconomics } from "./economics.ts";
+import { FINISHED_STATUSES } from "./highlights.ts";
+const MS_PER_WEEK = 7 * 86_400_000;
+const MS_PER_DAY = 86_400_000;
+export interface CostWeek {
+  weekStart: Date;
+  /** Hours per seat name ("agent", "human", …) as recorded, or as median. */
+  hoursBySeat: Record<string, number>;
+  hours: number;
+  /** Null when no bead in the week recorded tokens. */
+  tokensIn: number | null;
+  tokensOut: number | null;
+  /** Beads that contributed (closed with economics; or scheduled to land). */
+  beads: number;
+  /** True: read off records. False: medians placed by the schedule. */
+  measured: boolean;
+}
+export interface CostMedians {
+  hoursBySeat: Record<string, number>;
+  tokensIn: number | null;
+  tokensOut: number | null;
+  /** Beads the medians were taken over. */
+  sample: number;
+  /** "task" when the type had enough samples, "all" when it fell back. */
+  bucket: string;
+}
+export interface CostSeries {
+  past: CostWeek[];
+  projected: CostWeek[];
+  /** Every seat seen, most hours first, so stacks and tables share an order. */
+  seats: string[];
+  /** Closed beads with recorded economics, project-wide: the projection's evidence. */
+  sample: number;
+  /** Of those, records that declare themselves reconstructed rather than measured. */
+  reconstructed: number;
+  horizonWeeks: number;
+}
+export interface CostOptions {
+  /** Restrict to one person: measured by bead assignee, projected by the schedule's (resolved) assignee. */
+  handle?: string | null;
+  /** How far ahead to project, in days; rounded up to whole weeks, at most 12. */
+  horizonDays?: number;
+  now?: number;
+}
+/** Below this many beads of a type, the medians fall back to every type. */
+export const MIN_BUCKET_SAMPLE = 3;
+const MAX_HORIZON_WEEKS = 12;
+const isEpic = (b: Bead) => b.issue_type === "epic";
+function median(xs: number[]): number {
+  const s = [...xs].sort((a, b) => a - b);
+  const n = s.length;
+  if (!n) return 0;
+  return n % 2 ? s[(n - 1) / 2]! : (s[n / 2 - 1]! + s[n / 2]!) / 2;
+}
+interface Recorded {
+  bead: Bead;
+  hoursBySeat: Record<string, number>;
+  tokensIn: number | null;
+  tokensOut: number | null;
+  reconstructed: boolean;
+}
+/** Closed beads whose economics were written down, project-wide. */
+function recorded(beads: readonly Bead[]): Recorded[] {
+  const out: Recorded[] = [];
+  for (const b of beads) {
+    if (b.status !== "closed" || !b.closed_at) continue;
+    const e = buildEconomics(b);
+    if (!e.hasAny) continue;
+    const hoursBySeat: Record<string, number> = {};
+    for (const s of e.seats) hoursBySeat[s.seat] = (hoursBySeat[s.seat] ?? 0) + s.hours;
+    if (!e.seats.length && e.totals.agentHours !== null) hoursBySeat.agent = e.totals.agentHours;
+    // Tokens: the rolled-up totals when written, else summed from the
+    // sessions that carry them (this repo's records put them there).
+    let tokensIn = e.totals.tokensIn;
+    let tokensOut = e.totals.tokensOut;
+    if (tokensIn === null && tokensOut === null) {
+      for (const seat of e.seats) {
+        for (const ses of seat.sessions) {
+          if (ses.tokensIn !== null) tokensIn = (tokensIn ?? 0) + ses.tokensIn;
+          if (ses.tokensOut !== null) tokensOut = (tokensOut ?? 0) + ses.tokensOut;
+        }
+      }
+    }
+    const reconstructed = Object.values(e.provenance).some((p) => p?.kind === "reconstructed");
+    out.push({ bead: b, hoursBySeat, tokensIn, tokensOut, reconstructed });
+  }
+  return out;
+}
+/**
+ * Median cost of comparable shipped work, for one issue type. Hours per seat
+ * are medians over the beads that recorded that seat; tokens over the beads
+ * that recorded tokens. Null medians mean nobody wrote tokens down.
+ */
+export function costMedians(recs: readonly Recorded[], type: string): CostMedians {
+  let pool = recs.filter((r) => r.bead.issue_type === type);
+  let bucket = type;
+  if (pool.length < MIN_BUCKET_SAMPLE) {
+    pool = [...recs];
+    bucket = "all";
+  }
+  const seats = new Set<string>();
+  for (const r of pool) for (const s of Object.keys(r.hoursBySeat)) seats.add(s);
+  const hoursBySeat: Record<string, number> = {};
+  for (const s of seats) hoursBySeat[s] = median(pool.filter((r) => s in r.hoursBySeat).map((r) => r.hoursBySeat[s]!));
+  const tin = pool.filter((r) => r.tokensIn !== null).map((r) => r.tokensIn!);
+  const tout = pool.filter((r) => r.tokensOut !== null).map((r) => r.tokensOut!);
+  return {
+    hoursBySeat,
+    tokensIn: tin.length ? median(tin) : null,
+    tokensOut: tout.length ? median(tout) : null,
+    sample: pool.length,
+    bucket,
+  };
+}
+function emptyWeek(weekStart: Date, measured: boolean): CostWeek {
+  return { weekStart, hoursBySeat: {}, hours: 0, tokensIn: null, tokensOut: null, beads: 0, measured };
+}
+function addTo(w: CostWeek, hoursBySeat: Record<string, number>, tokensIn: number | null, tokensOut: number | null) {
+  for (const [s, h] of Object.entries(hoursBySeat)) {
+    w.hoursBySeat[s] = (w.hoursBySeat[s] ?? 0) + h;
+    w.hours += h;
+  }
+  if (tokensIn !== null) w.tokensIn = (w.tokensIn ?? 0) + tokensIn;
+  if (tokensOut !== null) w.tokensOut = (w.tokensOut ?? 0) + tokensOut;
+  w.beads += 1;
+}
+/**
+ * Past weeks in the ship trend's own buckets, projected weeks continuing
+ * the same grid from the end of the last bucket.
+ */
+export function costSeries(
+  beads: readonly Bead[],
+  schedule: Schedule | null,
+  weekly: ReadonlyArray<{ weekStart: Date }>,
+  opts: CostOptions = {},
+): CostSeries {
+  const now = opts.now ?? Date.now();
+  const handle = opts.handle ?? null;
+  const horizonWeeks = Math.max(1, Math.min(MAX_HORIZON_WEEKS, Math.ceil((opts.horizonDays ?? 56) / 7)));
+  const recs = recorded(beads);
+  // ── measured ──
+  const past: CostWeek[] = weekly.map((w) => emptyWeek(w.weekStart, true));
+  const gridStart = weekly.length ? weekly[0]!.weekStart.getTime() : now;
+  const gridEnd = weekly.length ? weekly[weekly.length - 1]!.weekStart.getTime() + MS_PER_WEEK : now;
+  for (const r of recs) {
+    if (handle && r.bead.assignee !== handle) continue;
+    const t = new Date(r.bead.closed_at!).getTime();
+    if (!(t >= gridStart && t < gridEnd)) continue;
+    const i = Math.min(past.length - 1, Math.floor((t - gridStart) / MS_PER_WEEK));
+    addTo(past[i]!, r.hoursBySeat, r.tokensIn, r.tokensOut);
+  }
+  // ── projected ──
+  const projected: CostWeek[] = Array.from({ length: horizonWeeks }, (_, k) => emptyWeek(new Date(gridEnd + k * MS_PER_WEEK), false));
+  const medianByType = new Map<string, CostMedians>();
+  if (schedule && recs.length) {
+    for (const b of beads) {
+      if (isEpic(b) || FINISHED_STATUSES.includes(b.status)) continue;
+      const sched = schedule.get(b.id);
+      if (!sched || sched.end_day < 0) continue;
+      if (handle && resolveAssignee(b, sched).handle !== handle) continue;
+      const landing = now + sched.end_day * MS_PER_DAY;
+      const k = Math.floor((landing - gridEnd) / MS_PER_WEEK);
+      if (k < 0 || k >= horizonWeeks) continue;
+      const type = b.issue_type ?? "task";
+      let m = medianByType.get(type);
+      if (!m) {
+        m = costMedians(recs, type);
+        medianByType.set(type, m);
+      }
+      addTo(projected[k]!, m.hoursBySeat, m.tokensIn, m.tokensOut);
+    }
+  }
+  const seatHours = new Map<string, number>();
+  for (const w of [...past, ...projected]) for (const [s, h] of Object.entries(w.hoursBySeat)) seatHours.set(s, (seatHours.get(s) ?? 0) + h);
+  const seats = [...seatHours.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([s]) => s);
+  return { past, projected, seats, sample: recs.length, reconstructed: recs.filter((r) => r.reconstructed).length, horizonWeeks };
+}
+/** Per-week averages over a run of weeks, for the head figures. */
+export function weeklyAverage(weeks: readonly CostWeek[]): { hours: number; hoursBySeat: Record<string, number>; tokensIn: number | null; tokensOut: number | null; beads: number } {
+  const n = Math.max(1, weeks.length);
+  const hoursBySeat: Record<string, number> = {};
+  let hours = 0;
+  let beads = 0;
+  let tin: number | null = null;
+  let tout: number | null = null;
+  for (const w of weeks) {
+    hours += w.hours;
+    beads += w.beads;
+    for (const [s, h] of Object.entries(w.hoursBySeat)) hoursBySeat[s] = (hoursBySeat[s] ?? 0) + h;
+    if (w.tokensIn !== null) tin = (tin ?? 0) + w.tokensIn;
+    if (w.tokensOut !== null) tout = (tout ?? 0) + w.tokensOut;
+  }
+  for (const s of Object.keys(hoursBySeat)) hoursBySeat[s] = hoursBySeat[s]! / n;
+  return { hours: hours / n, hoursBySeat, tokensIn: tin === null ? null : tin / n, tokensOut: tout === null ? null : tout / n, beads };
+}
+/** Hours with the precision the size needs: "12h", "3.4h", "0.38h" — never a "0.0h" that hides a number. */
+export function fmtHours(h: number): string {
+  if (h >= 10) return `${h.toFixed(0)}h`;
+  if (h >= 1) return `${h.toFixed(1)}h`;
+  if (h > 0) return `${h.toFixed(2)}h`;
+  return "0h";
+}
+/** "1.2k", "34k", "1.5M" — tokens are big numbers and the chart is small. */
+export function fmtTokens(n: number | null): string {
+  if (n === null) return "—";
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(n >= 1e4 ? 0 : 1)}k`;
+  return n.toFixed(0);
+}