beadcyte 0.4.0

package/src/web/components/WipBullets.vue

@@ -0,0 +1,191 @@
+<script setup lang="ts">
+// WipBullets.vue — per-person work in flight against the calibrated cap, as
+// bullet rows on one shared scale (bp-67g.29).
+//
+// The bar is in-flight work in --c-in-progress up to the cap; the run past
+// the cap continues in --c-danger at its real length; the notch at the cap
+// is --c-text. Those three are the "wip bullet" group the style audit
+// already guards, so a named style cannot collapse them. The value sits at
+// the tip and the cap/rate text at the end of the row, where the old chips
+// put it.
+
+import { computed } from "vue";
+import { capBlurb, rateBlurb, wipScaleMax, type WipRow } from "../wip";
+
+const props = defineProps<{
+  rows: WipRow[];
+  /** The person the incytes view is scoped to; their row is emphasised (bp-dgq). */
+  selected?: string | null;
+}>();
+// The handle is a way in to that person's picture (bp-67g.43); the parent
+// owns the navigation, like everything else in this presentational strip.
+const emit = defineEmits<{ select: [handle: string] }>();
+
+const scaleMax = computed(() => wipScaleMax(props.rows));
+const pos = (v: number) => `${Math.min(100, (v / scaleMax.value) * 100)}%`;
+</script>
+
+<template>
+  <ul class="wip-bullets" :aria-label="`Work in flight against calibrated cap, scale 0 to ${scaleMax}`">
+    <li
+      v-for="r in rows"
+      :key="r.handle"
+      class="wip-row"
+      :class="{ 'is-over': r.over > 0, 'is-idle': r.inFlight === 0, 'is-nudged': r.rawCap !== r.cap, 'is-selected': selected === r.handle }"
+    >
+      <button type="button" class="who" :title="`Show ${r.handle}`" @click="emit('select', r.handle)"><code>{{ r.handle }}</code></button>
+      <div
+        class="track"
+        role="img"
+        :aria-label="`${r.handle}: ${r.inFlight} in flight against a cap of ${r.cap}${r.over ? `, ${r.over} over` : ''}`"
+      >
+        <i class="fill" :style="{ width: pos(Math.min(r.inFlight, r.cap)) }" />
+        <i v-if="r.over > 0" class="over" :style="{ left: pos(r.cap), width: pos(r.over) }" />
+        <i class="cap" :style="{ left: pos(r.cap) }" />
+        <span class="tip" :style="{ left: pos(r.inFlight) }">{{ r.inFlight }}</span>
+      </div>
+      <span class="blurb">
+        <span class="cap-blurb">{{ capBlurb(r) }}</span>
+        <span class="rate">{{ rateBlurb(r) }}</span>
+      </span>
+    </li>
+  </ul>
+</template>
+
+<style>
+.wip-bullets {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  flex: 1 1 100%;
+  min-width: 0;
+}
+
+.wip-row {
+  display: grid;
+  grid-template-columns: minmax(64px, 110px) minmax(160px, 1fr) auto;
+  align-items: center;
+  gap: 10px;
+  font-size: 11px;
+}
+
+.wip-row .who {
+  all: unset;
+  cursor: pointer;
+  font-family: ui-monospace, monospace;
+  font-size: 11px;
+  color: var(--c-accent);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.wip-row .who code {
+  font: inherit;
+  color: inherit;
+}
+
+.wip-row .who:hover code,
+.wip-row .who:focus-visible code {
+  text-decoration: underline dotted;
+  text-underline-offset: 2px;
+}
+
+.wip-row.is-idle .who,
+.wip-row.is-idle .blurb {
+  opacity: 0.6;
+}
+
+/* The selected person, when incytes is scoped to one: the comparison with
+   everyone else is the point of a shared scale, so the others stay. */
+.wip-row.is-selected {
+  box-shadow: inset 3px 0 0 var(--c-accent);
+  padding-left: 6px;
+  margin-left: -9px;
+}
+
+.wip-row.is-selected .who,
+.wip-row.is-selected .blurb {
+  opacity: 1;
+  color: var(--c-text);
+}
+
+/* The measure. Padding-right leaves room for a tip value at 100%. */
+.wip-row .track {
+  position: relative;
+  height: 10px;
+  margin-right: 28px;
+  background: var(--c-lift);
+  border-radius: 2px;
+}
+
+.wip-row .fill,
+.wip-row .over {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  border-radius: 2px;
+}
+
+.wip-row .fill {
+  left: 0;
+  background: var(--c-in-progress);
+  opacity: 0.9;
+}
+
+.wip-row .over {
+  background: var(--c-danger);
+  opacity: 0.9;
+  border-radius: 0 2px 2px 0;
+}
+
+/* The cap is a notch ON the measure, not the end of the scale. */
+.wip-row .cap {
+  position: absolute;
+  top: -3px;
+  bottom: -3px;
+  width: 2px;
+  background: var(--c-text);
+  transform: translateX(-1px);
+}
+
+.wip-row .tip {
+  position: absolute;
+  top: -3px;
+  margin-left: 5px;
+  font-size: 10px;
+  line-height: 16px;
+  color: var(--c-text);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.wip-row.is-over .tip {
+  color: var(--c-danger);
+  font-weight: 600;
+}
+
+.wip-row .blurb {
+  display: inline-flex;
+  gap: 8px;
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+}
+
+.wip-row .cap-blurb {
+  color: var(--c-text);
+}
+
+.wip-row.is-nudged .cap-blurb {
+  color: var(--c-accent);
+  font-weight: 600;
+}
+
+.wip-row .rate {
+  color: var(--c-dim);
+  font-size: 10px;
+}
+</style>

package/src/web/components/filter-option.ts

@@ -0,0 +1,9 @@
+// Shared row shape for FilterPopover.vue. Kept out of the SFC so consumers
+// can `import type { FilterOption } from "./filter-option"` without pulling
+// the whole component's runtime.
+
+export interface FilterOption<T> {
+  value: T;
+  label: string;
+  hint?: string;
+}

package/src/web/composables/url-codec.ts

@@ -0,0 +1,136 @@
+// url-codec.ts — query-string encoding for shareable view state.
+//
+// Also owns the enum guards for the query string's closed-set params.
+//
+// Pure: no store, no window, no Vue. useUrlState.ts owns the reactive
+// wiring; this owns the wire format, so the format is testable on its own
+// (node:test can't resolve the composable's store import).
+
+import type { GroupBy } from "../view-model";
+
+/**
+ * Serialize an array of values to a comma-separated string.
+ * Empty/absent arrays serialize to "" so callers can drop the param.
+ */
+export function serializeArray(
+  arr: (string | number | null)[] | null | undefined,
+): string {
+  if (!arr || arr.length === 0) return "";
+  return arr.map((v) => (v === null ? "" : String(v))).join(",");
+}
+
+/**
+ * Deserialize a comma-separated string to a string array.
+ *
+ * Deliberately does NOT coerce numeric-looking segments to numbers: ids,
+ * labels, statuses and assignees are opaque strings, and a label like "2026"
+ * must round-trip as a string or it stops matching the bead it came from.
+ */
+export function deserializeStrings(str: string): string[] {
+  if (!str) return [];
+  return str
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Deserialize a comma-separated string to a number array, dropping any
+ * segment that is not a number (a hand-edited URL is untrusted input).
+ */
+export function deserializeNumbers(str: string): number[] {
+  if (!str) return [];
+  return str
+    .split(",")
+    .map((s) => Number(s.trim()))
+    .filter((n) => Number.isFinite(n));
+}
+
+/**
+ * Serialize a date to a plain ISO day (YYYY-MM-DD).
+ */
+export function serializeDate(date: Date | null | undefined): string {
+  if (!date) return "";
+  const t = date.getTime();
+  if (!Number.isFinite(t)) return "";
+  return date.toISOString().split("T")[0];
+}
+
+/**
+ * Parse a date string: ISO (2026-09-01) or relative ("-30d", "+90d").
+ * Returns null for anything unparseable -- `new Date(garbage)` yields an
+ * Invalid Date rather than throwing, so the result must be range-checked.
+ */
+export function parseDate(str: string): Date | null {
+  if (!str) return null;
+  const rel = str.match(/^([+-])(\d+)d$/);
+  if (rel) {
+    const sign = rel[1] === "+" ? 1 : -1;
+    const date = new Date();
+    date.setDate(date.getDate() + sign * Number(rel[2]));
+    return date;
+  }
+  const date = new Date(str);
+  return Number.isFinite(date.getTime()) ? date : null;
+}
+
+/**
+ * Which view is mounted. Part of the URL rather than localStorage: a shared
+ * link should land the recipient on the view the sender was looking at.
+ */
+export type ViewMode = "mine" | "gantt" | "grid" | "table" | "incytes";
+
+const VIEW_MODES: readonly ViewMode[] = ["mine", "gantt", "grid", "table", "incytes"];
+
+const GROUP_MODES: readonly GroupBy[] = [
+  "epic",
+  "assignee",
+  "seat",
+  "track",
+  "status",
+  "priority",
+  "none",
+];
+
+/**
+ * Parse `?view=`, falling back to the mine view (the default tab). The query string is
+ * user-editable, so an unrecognised value is ignored rather than trusted —
+ * which is also what keeps links written before a view existed working.
+ */
+export function parseView(str: string | null | undefined): ViewMode {
+  return str && (VIEW_MODES as readonly string[]).includes(str)
+    ? (str as ViewMode)
+    : "mine";
+}
+
+/**
+ * Parse `?group=`, returning null when the value isn't a real mode so the
+ * caller can leave the store's default alone. An unrecognised value used to
+ * be cast straight through, landing the view model on its "__all" fallback
+ * with no mode showing as active in the controls.
+ */
+export function parseGroupBy(str: string | null | undefined): GroupBy | null {
+  return str && (GROUP_MODES as readonly string[]).includes(str)
+    ? (str as GroupBy)
+    : null;
+}
+
+/**
+ * Which normally-hidden statuses a pre-bp-67g.40 link was asking for.
+ *
+ * `?showClosed=true` and `?includeDeferred=true` were separate booleans that
+ * silently overrode `?status=`. They are no longer written, but old links are
+ * shareable state and have to keep resolving to the same view, so they are
+ * still read — as statuses to add to the default selection.
+ *
+ * Returns [] when neither is present or both are false, which is also the
+ * shape a modern link produces. An explicit `?status=` in the same URL is the
+ * newer and more specific instruction and should win outright; that call
+ * belongs to the caller, which has the parsed status list.
+ */
+export function legacyHiddenStatuses(params: URLSearchParams): string[] {
+  const out: string[] = [];
+  if (params.get("showClosed") === "true") out.push("closed");
+  if (params.get("includeDeferred") === "true") out.push("deferred");
+  return out;
+}

package/src/web/composables/useBeadTooltip.ts

@@ -0,0 +1,148 @@
+// useBeadTooltip.ts — one hover state machine for every BeadTooltip host
+// (bp-67g.42).
+//
+// The Gantt grew this for its bars (bp-6y1, bp-67g.41): hovering a mark pins
+// the panel at the entry point, a short grace period on leave lets the pointer
+// cross the gap onto the panel, and the panel's rows — detail, triage score
+// and rank, time spent, watched — are resolved through the store. The drawer's
+// dependency subgraph needs exactly the same behaviour for its nodes, so the
+// machine lives here and both hosts render `<BeadTooltip v-bind="tipProps">`.
+// One definition, so the two hovers cannot drift apart in what they say.
+
+import { computed, onUnmounted, ref } from "vue";
+import { useBeadsStore } from "../store";
+import { describeRank } from "../triage";
+import { buildEconomics } from "../economics";
+
+export interface BeadTooltipOptions {
+  /** Grace period in ms between leaving the mark and the panel closing. */
+  leaveDelayMs?: number;
+  /**
+   * Close the panel when anything scrolls — the host's own overflow, the
+   * drawer body, the page. The panel is fixed to the viewport while the mark
+   * it describes scrolls away, so a scroll would otherwise leave it stranded.
+   */
+  dismissOnScroll?: boolean;
+  /**
+   * The horizontal extent, in viewport px, the panel must stay inside. A host
+   * that lives in a column (the drawer) passes its own edges; the Gantt has
+   * the whole viewport and passes nothing. Read at hover time.
+   */
+  bounds?: () => { left: number; right: number } | null;
+}
+
+export function useBeadTooltip(opts: BeadTooltipOptions = {}) {
+  const store = useBeadsStore();
+  const leaveDelay = opts.leaveDelayMs ?? 180;
+
+  const hoveredBeadId = ref<string | null>(null);
+  const hoverX = ref(0);
+  const hoverY = ref(0);
+  // The hovered mark's band in viewport px, so the panel can stay off it.
+  const hoverBand = ref<{ top: number; bottom: number } | null>(null);
+  const hoverBounds = ref<{ left: number; right: number } | null>(null);
+  let leaveTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const detail = computed(() =>
+    hoveredBeadId.value ? store.beadDetailFor(hoveredBeadId.value) : null,
+  );
+  const watched = computed(
+    () => !!hoveredBeadId.value && store.watchedSet.has(hoveredBeadId.value),
+  );
+  // Reading store.triage from a hover was the cost bp-67g.41 flagged;
+  // bp-67g.25 took it from ~300ms to a few ms on a 600-bead graph, so the
+  // first hover pays a blink, not a stall. Economics is a per-bead derivation
+  // over its own metadata and timestamps.
+  const triage = computed(() =>
+    hoveredBeadId.value ? store.triage.get(hoveredBeadId.value) ?? null : null,
+  );
+  const rank = computed(() =>
+    triage.value ? describeRank(store.triageScorePopulation, triage.value.score) : null,
+  );
+  const economics = computed(() => {
+    const id = hoveredBeadId.value;
+    const b = id ? store.beads.find((x) => x.id === id) : undefined;
+    return b ? buildEconomics(b) : null;
+  });
+
+  /** Everything BeadTooltip takes, ready for `v-bind`. */
+  const props = computed(() => ({
+    detail: detail.value,
+    x: hoverX.value,
+    y: hoverY.value,
+    watched: watched.value,
+    bandTop: hoverBand.value?.top,
+    bandBottom: hoverBand.value?.bottom,
+    boundsLeft: hoverBounds.value?.left,
+    boundsRight: hoverBounds.value?.right,
+    triage: triage.value,
+    rank: rank.value,
+    economics: economics.value,
+  }));
+
+  let listeningForScroll = false;
+  const onAnyScroll = () => dismiss();
+  function listenForScroll() {
+    if (listeningForScroll || !opts.dismissOnScroll) return;
+    // Scroll events do not bubble, but they do pass document in the capture
+    // phase, so one listener sees every scroll container on the page.
+    document.addEventListener("scroll", onAnyScroll, { capture: true, passive: true });
+    listeningForScroll = true;
+  }
+  function stopListeningForScroll() {
+    if (!listeningForScroll) return;
+    document.removeEventListener("scroll", onAnyScroll, { capture: true });
+    listeningForScroll = false;
+  }
+
+  function cancelLeave() {
+    if (leaveTimer) {
+      clearTimeout(leaveTimer);
+      leaveTimer = null;
+    }
+  }
+
+  /** The mark or the panel was left: close after the grace period. */
+  function scheduleLeave() {
+    cancelLeave();
+    leaveTimer = setTimeout(() => dismiss(), leaveDelay);
+  }
+
+  /** Close now: the bead was opened, the picture changed, something scrolled. */
+  function dismiss() {
+    cancelLeave();
+    hoveredBeadId.value = null;
+    stopListeningForScroll();
+  }
+
+  /**
+   * A mark for `id` was entered. The panel is pinned where the pointer came
+   * in (it does not follow the mouse, so the pointer can leave the mark for
+   * the panel) and anchored to `mark`'s band — the event's currentTarget
+   * unless the host names a tighter element, as the subgraph does with its
+   * node box inside a larger hit area.
+   */
+  function enter(id: string, e: MouseEvent, mark?: Element | null) {
+    cancelLeave();
+    hoveredBeadId.value = id;
+    hoverX.value = e.clientX;
+    hoverY.value = e.clientY;
+    const r = (mark ?? (e.currentTarget as Element | null))?.getBoundingClientRect();
+    hoverBand.value = r ? { top: r.top - 4, bottom: r.bottom + 4 } : null;
+    hoverBounds.value = opts.bounds?.() ?? null;
+    listenForScroll();
+  }
+
+  /**
+   * Pin from the panel. The panel stays open: the user is looking at the
+   * bead they just pinned, and the button flips to its unwatch state.
+   */
+  function toggleWatch(id: string) {
+    store.toggleWatch(id);
+    cancelLeave();
+  }
+
+  onUnmounted(dismiss);
+
+  return { hoveredBeadId, props, enter, scheduleLeave, cancelLeave, dismiss, toggleWatch };
+}

package/src/web/composables/useKeyboard.ts

@@ -0,0 +1,97 @@
+// useKeyboard.ts — listens for the shortcuts keybindings.ts declares and
+// carries each out (bp-67g.45). One document listener, installed by App.vue.
+//
+// The table decides WHAT is bound; this file decides what each action does,
+// against the store and the theme. Nothing here adds a key the table does
+// not list, so the ? overlay stays the whole truth.
+
+import { onBeforeUnmount, onMounted } from "vue";
+import { useBeadsStore } from "../store";
+import { useTheme } from "./useTheme";
+import { STYLE_NAMES, type StyleName } from "../theme";
+import { WINDOW_PRESETS } from "../window";
+import { isTypingTarget, matchBinding, type KeyAction } from "../keybindings";
+import { markWalkthroughSeen } from "../walkthrough";
+import type { GroupBy } from "../view-model";
+
+const GROUP_CYCLE: readonly GroupBy[] = ["epic", "assignee", "seat", "track", "status", "priority", "none"];
+
+export function useKeyboard() {
+  const store = useBeadsStore();
+  const theme = useTheme();
+
+  function next<T>(list: readonly T[], current: T): T {
+    const i = list.indexOf(current);
+    return list[(i + 1) % list.length]!;
+  }
+
+  function run(action: KeyAction) {
+    switch (action) {
+      case "view-mine": return store.setView("mine");
+      case "view-gantt": return store.setView("gantt");
+      case "view-grid": return store.setView("grid");
+      case "view-table": return store.setView("table");
+      case "view-incytes": return store.setView("incytes");
+      case "cycle-group": return store.setGroupBy(next(GROUP_CYCLE, store.groupBy));
+      case "cycle-window": {
+        const ids = WINDOW_PRESETS.map((p) => p.id);
+        const cur = store.activeWindowPreset;
+        return store.setWindowFromPreset(cur ? next(ids, cur) : ids[0]!);
+      }
+      case "today":
+        store.setWindowFromPreset("90d");
+        return store.requestToday();
+      case "next-bead": return store.moveCursor(1);
+      case "prev-bead": return store.moveCursor(-1);
+      case "open-first": return store.openBeadId ? undefined : store.moveCursor(1);
+      case "close":
+        if (store.contextMenu) return store.closeContextMenu();
+        if (store.helpOpen) return store.closeHelp();
+        if (store.changelogOpen) return store.closeChangelog();
+        if (store.openBeadId) return store.closeBead();
+        if (store.walkthroughOpen) {
+          markWalkthroughSeen();
+          return store.closeWalkthrough();
+        }
+        return;
+      case "toggle-watch": return store.openBeadId ? store.toggleWatch(store.openBeadId) : undefined;
+      case "toggle-scope": return store.toggleDrawerSubgraphScope();
+      case "actions": {
+        if (!store.openBeadId) return;
+        // Anchor at the drawer's Actions button when it is on screen.
+        const r = document.querySelector(".drawer .actions-btn")?.getBoundingClientRect();
+        return store.openContextMenu(store.openBeadId, r ? r.left : 24, r ? r.bottom + 4 : 24);
+      }
+      case "copy-id":
+        if (store.openBeadId) void navigator.clipboard?.writeText(store.openBeadId);
+        return;
+      case "hl-blocked": return store.toggleHighlight("blocked");
+      case "hl-over-cap": return store.toggleHighlight("over-cap");
+      case "hl-ready-now": return store.toggleHighlight("ready-now");
+      case "toggle-deps": return store.toggleShowDependencies();
+      case "clear-filters": return store.resetFilters();
+      case "toggle-closed": return store.toggleStatusInFilter("closed");
+      case "cycle-theme": return theme.cycleMode();
+      case "cycle-style": return theme.setStyle(next(STYLE_NAMES as readonly StyleName[], theme.style.value));
+      case "options": return store.requestOptions();
+      case "search": return store.requestSearch();
+      case "help": return store.helpOpen ? store.closeHelp() : store.openHelp();
+    }
+  }
+
+  function onKeydown(e: KeyEvent) {
+    if (e.defaultPrevented) return;
+    if (isTypingTarget(e.target as HTMLElement | null)) return;
+    const b = matchBinding(e);
+    if (!b) return;
+    // Escape with nothing to close is the browser's; everything else is ours.
+    if (b.action === "close" && !store.contextMenu && !store.helpOpen && !store.changelogOpen && !store.openBeadId && !store.walkthroughOpen) return;
+    e.preventDefault();
+    run(b.action);
+  }
+
+  type KeyEvent = KeyboardEvent;
+
+  onMounted(() => document.addEventListener("keydown", onKeydown));
+  onBeforeUnmount(() => document.removeEventListener("keydown", onKeydown));
+}

package/src/web/composables/useLiveRefresh.ts

@@ -0,0 +1,69 @@
+// useLiveRefresh.ts — the poll timer.
+//
+// The interval and the "off" choice are settings owned by the options menu
+// (refresh.ts); this acts on them.
+//
+// Three rules, each for a reason:
+//
+//  - Paused while the tab is hidden. Every tick shells out to `bd`, and a
+//    backgrounded tab burning that for nobody is pure waste.
+//  - No backfill on return. A tab hidden for an hour owes one fetch, not
+//    sixty; setInterval would queue them, so the timer is torn down on hide
+//    and rebuilt on show.
+//  - Refetches on becoming visible even when polling is OFF. Off means "no
+//    timer", not "show me stale data without saying so" — and returning to
+//    a tab is exactly when stale data is most likely to be acted on.
+
+import { onBeforeUnmount, onMounted, watch } from "vue";
+import { useBeadsStore } from "../store";
+import { isRefreshOff } from "../refresh";
+
+export function useLiveRefresh() {
+  const store = useBeadsStore();
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  const stop = () => {
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+
+  const start = () => {
+    stop();
+    const ms = store.pollIntervalMs;
+    if (isRefreshOff(ms)) return;
+    if (typeof document !== "undefined" && document.hidden) return;
+    timer = setInterval(() => {
+      // Skip a tick that lands while a fetch is still in flight rather than
+      // stacking requests on a slow repo.
+      if (!store.loading) void store.fetch();
+    }, ms);
+  };
+
+  function onVisibilityChange() {
+    if (document.hidden) {
+      stop();
+      return;
+    }
+    // One catch-up fetch, then resume ticking. This runs whatever the
+    // interval is, including off.
+    if (!store.loading) void store.fetch();
+    start();
+  }
+
+  onMounted(() => {
+    start();
+    document.addEventListener("visibilitychange", onVisibilityChange);
+  });
+
+  onBeforeUnmount(() => {
+    stop();
+    document.removeEventListener("visibilitychange", onVisibilityChange);
+  });
+
+  // Changing the interval takes effect now, not after the old one fires.
+  watch(() => store.pollIntervalMs, start);
+
+  return { restart: start, stop };
+}