@gperezmz/bb-plugin-thread-glance 0.2.3 → 0.3.0

package/features/thread-list/model/labels.ts

@@ -1,7 +1,8 @@
 // Accessible names: everything a tooltip says is in the aria-label.
-import type { OlderRow, ThreadRow } from "./view";
+import type { OlderRow, SettledRow, ThreadRow } from "./view";
 import { FLAG_GLYPHS, type Flag } from "./state";
 import { formatDateTime } from "./details";
+import type { OrganizationMode } from "@/shared/preferences";
 
 export function stateText(row: ThreadRow, pluginLabel: string | null): string {
   const state = row.info.state;
@@ -19,33 +20,43 @@ export function rowAriaLabel(
 ): string {
   const parts = [stateText(row, options.pluginLabel), options.providerName];
   if (row.parentTitle !== null && row.depth > 0) parts.push(`child of ${row.parentTitle}`);
+  if (row.childDot !== null) parts.push(`child threads: ${FLAG_GLYPHS[row.childDot].label}`);
   if (row.crossGroupLabel !== null) parts.push(row.crossGroupLabel.toLowerCase());
-  if (row.homeGroupLabel !== null) parts.push(`in ${row.homeGroupLabel}`);
   if (row.hiddenBadge) parts.push("hidden thread");
   if (row.info.unread && row.info.state.kind !== "unread") parts.push("unread");
   if (options.hasDraft && row.info.state.kind !== "draft") parts.push("unsubmitted draft");
   return `Open ${row.info.thread.displayTitle} — ${parts.join("; ")}`;
 }
 
-export function chipLabel(title: string, count: number, flag: Flag | null, expanded: boolean): string {
+export function chipLabel(title: string, count: number, expanded: boolean): string {
   const noun = count === 1 ? "child thread" : "child threads";
-  const detail = flag === null ? "" : `, ${FLAG_GLYPHS[flag].label}`;
-  return `${expanded ? "Collapse" : "Show"} ${count} ${noun} of ${title}${detail}`;
+  return `${expanded ? "Collapse" : "Show"} ${count} ${noun} of ${title}`;
 }
 
-/**
- * The fold row's text and accessible name. The family's row says "child
- * threads" so it never reads like the group's "older" row.
- */
+/** The text and accessible name of an open tree's fold row. */
 export function olderRowText(row: OlderRow): { label: string; ariaLabel: string } {
-  const noun = row.count === 1 ? "thread" : "threads";
-  if (row.scope === "group") {
-    return {
-      label: row.expanded ? "Show fewer" : `${row.count} older`,
-      ariaLabel: `${row.expanded ? "Hide" : "Show"} ${row.count} older ${noun}`,
-    };
-  }
   const children = row.count === 1 ? "child thread" : "child threads";
-  if (row.expanded) return { label: "Show fewer", ariaLabel: `Hide ${row.count} older ${children}` };
+  if (row.expanded) return { label: "Show fewer", ariaLabel: `Hide ${row.count} more ${children}` };
   return { label: `${row.count} more ${children}`, ariaLabel: `Show ${row.count} more ${children}` };
 }
+
+/** The settled fold's text: "Settled (N)" while closed, "Settled" while open. N counts trees. */
+export function settledRowText(row: SettledRow): { label: string; ariaLabel: string } {
+  const noun = row.count === 1 ? "settled thread tree" : "settled thread trees";
+  return {
+    label: row.expanded ? "Settled" : `Settled (${row.count})`,
+    ariaLabel: `${row.expanded ? "Hide" : "Show"} ${row.count} ${noun}`,
+  };
+}
+
+/** The list header's name for the current grouping. */
+export function groupingName(mode: OrganizationMode): string {
+  switch (mode) {
+    case "project":
+      return "Projects";
+    case "chronological":
+      return "Sections";
+    case "machine":
+      return "Machines";
+  }
+}

package/features/thread-list/model/layout.ts

@@ -1,9 +1,12 @@
 // How far a row sits from the list's left edge. Pure, so a test can
 // call it without rendering.
-/** Left padding of a root row, as in bb's list. */
+/**
+ * Left padding of a root row: its Status column starts where the group
+ * header's text does.
+ */
 export const ROOT_INDENT = 8;
 /**
- * A child's status slot starts this far right of its parent's, so the
+ * A child's Status column starts this far right of its parent's, so the
  * child's title sits this far right of the parent's title.
  */
 export const FOLDED_STEP = 12;

package/features/thread-list/model/menu.ts

@@ -30,6 +30,7 @@ export interface RowMenuItem {
 
 export interface RowMenuInputs {
   thread: PluginSidebarThread;
+  /** The thread is unread; for a root, anything in its tree is, and Mark read marks the tree. */
   unread: boolean;
   splitAvailable: boolean;
   /** True for a thread with no parent (bb: Move to section on roots only). */

package/features/thread-list/model/move.ts

@@ -1,5 +1,5 @@
 // "Move…": the keyboard route to what drag and drop does. Pure.
-import type { Forest } from "./families";
+import type { Forest } from "./trees";
 import { isInSubtree } from "./drag";
 
 export interface MoveTarget {

package/features/thread-list/model/notes.ts

@@ -2,10 +2,10 @@
 // the server stores what it saw; this decides what a row says.
 import type { PluginSidebarThread } from "@get-bb/plugin-sdk/app";
 import type { Note, ThreadNotes } from "@/shared/contract";
-import { normalizeQueued, normalizeStatus, type Flag, type NeedsKind } from "./state";
+import { normalizeQueued, normalizeStatus, type NeedsKind } from "./state";
 
 export interface RowNote {
-  /** "Asks", "Approve", "Plan", "Failed", "Offline", "Finished"… */
+  /** "Asks", "Approve", "Plan", "Needs" or "Failed". */
   prefix: string;
   /** Empty when there is nothing to add: the prefix stands alone. */
   text: string;
@@ -48,32 +48,6 @@ export function rowNote(thread: PluginSidebarThread, notes: ThreadNotes | undefi
   return null;
 }
 
-/**
- * The line under a row in Needs attention that itself needs attention: its
- * most urgent reason among `attention`, its Needs attention flags. Waits on
- * you, then failed, then offline, then finished; each keeps its prefix when
- * there is no text to follow it.
- */
-export function attentionNote(
-  thread: PluginSidebarThread,
-  notes: ThreadNotes | undefined,
-  attention: ReadonlySet<Flag>,
-): RowNote | null {
-  if (attention.has("waits-on-you")) {
-    return { prefix: PENDING_PREFIX[needsKindOf(notes) ?? "input"], text: notes?.pending?.text.trim() ?? "", tone: "attention" };
-  }
-  if (attention.has("unread-failed")) {
-    const text = notes?.failed?.text.trim() ?? "";
-    return { prefix: "Failed", text: text.toLowerCase() === "failed" ? "" : text, tone: "destructive" };
-  }
-  if (attention.has("queue-failed")) {
-    return { prefix: "Failed", text: "queued message wasn't sent", tone: "destructive" };
-  }
-  if (attention.has("offline")) return { prefix: "Offline", text: thread.host?.name.trim() ?? "", tone: "attention" };
-  if (attention.has("unread")) return { prefix: "Finished", text: lastReply(notes)?.text.trim() ?? "", tone: "muted" };
-  return null;
-}
-
 /** A note as one line of text: "Failed: timeout", or "Failed" alone. */
 export function noteText(note: RowNote): string {
   return note.text === "" ? note.prefix : `${note.prefix}: ${note.text}`;

package/features/thread-list/model/settings.ts

@@ -1,23 +1,7 @@
-// What the settings popover's controls show and write. Pure.
-import type { ChildAttention, Lifecycle, Preferences, SortField } from "@/shared/preferences";
+// What the settings panel's controls show and write. Pure.
+import type { ChildAttention, Preferences, SortField } from "@/shared/preferences";
 import { effectiveDirection, effectiveSortField, naturalDirection } from "./sort";
 
-export type ThreadsShown = "active" | "archived" | "both";
-
-/** The Threads choice a saved lifecycle list stands for. */
-export function threadsShown(lifecycles: readonly Lifecycle[]): ThreadsShown {
-  const active = lifecycles.includes("active");
-  const archived = lifecycles.includes("archived");
-  if (active && archived) return "both";
-  return archived ? "archived" : "active";
-}
-
-/** The lifecycles a Threads choice saves; never empty. */
-export function lifecyclesFor(shown: ThreadsShown): Lifecycle[] {
-  if (shown === "both") return ["active", "archived"];
-  return [shown];
-}
-
 /** "Needs attention counts every child" is on when children count as `everything`. */
 export function countsEveryChild(childAttention: ChildAttention): boolean {
   return childAttention === "everything";

package/features/thread-list/model/settled.ts

@@ -0,0 +1,122 @@
+// Settled threads: which trees go behind their group's settled fold.
+// Worked out afresh on every build, so any activity unsettles a thread. Pure.
+import type { PluginSidebarThread } from "@get-bb/plugin-sdk/app";
+import type { SettleAfter } from "@/shared/preferences";
+import { isQuietThread } from "./state";
+import type { ThreadInfo, ThreadTree } from "./trees";
+
+const HOUR = 60 * 60 * 1000;
+
+/** How long a thread goes without activity before it settles, per Settle after choice. */
+export const SETTLE_AFTER_MS: Readonly<Record<Exclude<SettleAfter, "never">, number>> = {
+  "12h": 12 * HOUR,
+  "1d": 24 * HOUR,
+  "3d": 3 * 24 * HOUR,
+  "1w": 7 * 24 * HOUR,
+};
+
+/** A pull request's state, as bb's lookup reports it. */
+export type PullRequestState = "open" | "draft" | "merged" | "closed";
+
+/**
+ * What settling knows of a thread's pull request: its state, null when the
+ * thread has none, or `unknown` while a lookup it needs has not answered.
+ */
+export type PullRequestFact = PullRequestState | null | "unknown";
+
+/**
+ * Whether a thread's branch can carry a pull request worth looking up: it is
+ * on a branch other than its project's default. A default branch the lookup
+ * could not find (null) is no reason to skip one; one still being looked up
+ * (undefined) is, until it answers.
+ */
+export function needsPullRequestLookup(branch: string | null, defaultBranch: string | null | undefined): boolean {
+  return branch !== null && defaultBranch !== undefined && branch !== defaultBranch;
+}
+
+/** A thread's pull request fact, from its project's default branch and the lookups that answered. */
+export function pullRequestFact(
+  thread: Pick<PluginSidebarThread, "id" | "environment">,
+  defaultBranch: string | null | undefined,
+  answers: ReadonlyMap<string, PullRequestState | null>,
+): PullRequestFact {
+  const branch = thread.environment?.branchName ?? null;
+  if (branch === null) return null;
+  if (defaultBranch === undefined) return "unknown";
+  if (!needsPullRequestLookup(branch, defaultBranch)) return null;
+  const answer = answers.get(thread.id);
+  return answer === undefined ? "unknown" : answer;
+}
+
+export interface SettleInputs {
+  now: number;
+  settleAfter: SettleAfter;
+  /** Server stamps: when each thread last started and finished a turn. */
+  startedAt: Readonly<Record<string, number>>;
+  finishedAt: Readonly<Record<string, number>>;
+  pullRequestOf(thread: PluginSidebarThread): PullRequestFact;
+}
+
+/**
+ * A thread's own last activity: its creation, its last finish or failure
+ * (`latestAttentionAt`) and the server's stamps of its last start and
+ * finish. `updatedAt` is left out because opening or renaming a thread
+ * moves it too.
+ */
+export function lastActivityAt(
+  thread: Pick<PluginSidebarThread, "id" | "createdAt" | "latestAttentionAt">,
+  stamps: Pick<SettleInputs, "startedAt" | "finishedAt">,
+): number {
+  return Math.max(
+    thread.createdAt,
+    thread.latestAttentionAt,
+    stamps.startedAt[thread.id] ?? 0,
+    stamps.finishedAt[thread.id] ?? 0,
+  );
+}
+
+/**
+ * A settled thread: quiet as if no thread were open, not needing attention,
+ * not pinned, with no open pull request, and either its pull request merged
+ * or closed or its own last activity is older than the Settle after period.
+ * Hidden and archived threads take the same test.
+ */
+export function isSettledThread(info: ThreadInfo, inputs: SettleInputs): boolean {
+  const thread = info.thread;
+  if (!mightSettle(info)) return false;
+  const pullRequest = inputs.pullRequestOf(thread);
+  if (pullRequest === "unknown" || pullRequest === "open" || pullRequest === "draft") return false;
+  if (pullRequest === "merged" || pullRequest === "closed") return true;
+  if (inputs.settleAfter === "never") return false;
+  return inputs.now - lastActivityAt(thread, inputs) >= SETTLE_AFTER_MS[inputs.settleAfter];
+}
+
+/** A row's thread that settles once its pull request and activity allow: quiet as if none were open, needing no attention, not pinned. */
+function mightSettle(info: ThreadInfo): boolean {
+  const thread = info.thread;
+  if (thread.pinnedAt !== null || thread.isPinned) return false;
+  return isQuietThread(info.state, info.unread, false) && info.attentionFlags.size === 0;
+}
+
+/** A tree settles as one unit: when every thread in it is settled. */
+export function isSettledTree(tree: Pick<ThreadTree, "root" | "descendants">, inputs: SettleInputs): boolean {
+  return isSettledThread(tree.root, inputs) && tree.descendants.every((info) => isSettledThread(info, inputs));
+}
+
+/**
+ * The threads whose pull request settling has to look up: every thread that
+ * would settle but for its pull request, on a branch other than its
+ * project's default.
+ */
+export function pullRequestLookupIds(
+  infos: Iterable<ThreadInfo>,
+  defaultBranchOf: (thread: PluginSidebarThread) => string | null | undefined,
+): string[] {
+  const ids: string[] = [];
+  for (const info of infos) {
+    const thread = info.thread;
+    if (!mightSettle(info)) continue;
+    if (needsPullRequestLookup(thread.environment?.branchName ?? null, defaultBranchOf(thread))) ids.push(thread.id);
+  }
+  return ids;
+}

package/features/thread-list/model/share.ts

@@ -1,6 +1,6 @@
 // Structural sharing between two list views: whatever did not change keeps
 // the previous object, so memoized rows and groups skip their render. Pure.
-import type { GroupView, ListView, AttentionView, Row } from "./view";
+import type { GroupView, ListView, Row } from "./view";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   if (value === null || typeof value !== "object") return false;
@@ -86,11 +86,6 @@ function shareGroups(previousGroups: GroupView[], all: ReadonlyMap<string, Group
   return sameItems(previousGroups, result) ? previousGroups : result;
 }
 
-function shareAttention(previous: AttentionView | null, next: AttentionView | null): AttentionView | null {
-  if (previous === null || next === null) return next;
-  return shareFields(previous, next, { rows: shareRows(previous.rows, next.rows) });
-}
-
 /**
  * `next`, sharing every group and row that did not change since `previous`.
  * Groups match by id and rows by key, never by position. A group keeps its
@@ -100,7 +95,6 @@ export function shareView(previous: ListView | null, next: ListView): ListView {
   if (previous === null) return next;
   const all = new Map([...previous.groups, ...previous.more].map((group) => [group.descriptor.id, group]));
   return shareFields(previous, next, {
-    attention: shareAttention(previous.attention, next.attention),
     groups: shareGroups(previous.groups, all, next.groups),
     more: shareGroups(previous.more, all, next.more),
   });

package/features/thread-list/model/sort.ts

@@ -5,14 +5,13 @@ import type { SortDirection, SortField } from "@/shared/preferences";
 export interface SortOptions {
   field: SortField;
   direction: SortDirection;
-  workingFirst: boolean;
 }
 
 /** What a comparator needs to know about a root beyond the thread itself. */
 export interface SortKey {
   thread: PluginSidebarThread;
-  /** Largest `latestAttentionAt` over the family. */
-  familyAttention: number;
+  /** Largest `latestAttentionAt` over the tree. */
+  treeAttention: number;
 }
 
 function byCreated(a: SortKey, b: SortKey): number {
@@ -28,7 +27,7 @@ function byAlpha(a: SortKey, b: SortKey): number {
 }
 
 function byUpdated(a: SortKey, b: SortKey): number {
-  const diff = b.familyAttention - a.familyAttention;
+  const diff = b.treeAttention - a.treeAttention;
   if (diff !== 0) return diff;
   return byCreated(a, b);
 }
@@ -48,22 +47,12 @@ export function effectiveDirection(field: SortField, direction: SortDirection):
   return direction === "default" ? naturalDirection(field) : direction;
 }
 
-/**
- * The comparator for roots in a group. Working first keeps active threads on
- * top whatever the direction.
- */
+/** The comparator for roots in a group. */
 export function makeComparator(options: SortOptions): (a: SortKey, b: SortKey) => number {
   const field = effectiveSortField(options.field);
   const sign = effectiveDirection(field, options.direction) === naturalDirection(field) ? 1 : -1;
   const base = field === "alpha" ? byAlpha : field === "created" ? byCreated : byUpdated;
-  return (a, b) => {
-    if (field === "updated" && options.workingFirst) {
-      const aActive = a.thread.status === "active";
-      const bActive = b.thread.status === "active";
-      if (aActive !== bActive) return aActive ? -1 : 1;
-    }
-    return sign * base(a, b);
-  };
+  return (a, b) => sign * base(a, b);
 }
 
 /** Pinned order: pinSortKey, then pinnedAt desc, createdAt desc, id. */

package/features/thread-list/model/state.ts

@@ -48,9 +48,12 @@ const NEEDS: Record<NeedsKind, { icon: string; label: string }> = {
   input: { icon: "MessageQuestion", label: "Needs your input" },
 };
 
-/** How a glyph is drawn. `dot` is the unread dot; everything else a host icon. */
+/**
+ * How a glyph is drawn. `dot` is the unread dot, `ring` the Idle state's
+ * faint ring; everything else a host icon.
+ */
 export interface Glyph {
-  icon: string | "dot" | null;
+  icon: string | "dot" | "ring";
   tone: Tone;
   spin: boolean;
   shine: boolean;
@@ -231,7 +234,7 @@ export function computeState(thread: PluginSidebarThread, inputs: StateInputs):
   }
   if (inputs.unread) return { kind: "unread", label: "Unread", glyph: glyph("dot", "none"), ...none };
   if (inputs.hasDraft) return { kind: "draft", label: "Unsubmitted draft", glyph: glyph("Edit", "muted"), ...none };
-  return { kind: "idle", label: "Idle", glyph: glyph(null, "none"), ...none };
+  return { kind: "idle", label: "Idle", glyph: glyph("ring", "muted"), ...none };
 }
 
 /**
@@ -268,26 +271,39 @@ export function hiddenThreadFlags(flags: ReadonlySet<Flag>): Set<Flag> {
   return kept;
 }
 
+/** Flags a hidden thread adds to its parent's child dot: what asks for you or failed, and offline. */
+const HIDDEN_DOT_FLAGS: ReadonlySet<Flag> = new Set<Flag>(["waits-on-you", "unread-failed", "queue-failed", "offline"]);
+
+/**
+ * The flags a thread adds to the child dot of the threads above it. A
+ * hidden thread adds only waits-on-you, failed, queued message failed and
+ * offline; which trees need attention reads `hiddenThreadFlags` instead,
+ * so this leaves it unchanged.
+ */
+export function dotFlagsOf(flags: ReadonlySet<Flag>, isHidden: boolean): Set<Flag> {
+  return isHidden ? new Set([...flags].filter((flag) => HIDDEN_DOT_FLAGS.has(flag))) : new Set(flags);
+}
+
 /** The most urgent flag, or null. */
 export function mostUrgent(flags: ReadonlySet<Flag>): Flag | null {
   return FLAG_ORDER.find((flag) => flags.has(flag)) ?? null;
 }
 
-/** The colour a child chip takes: only what asks for you, fails, or works. */
-export type ChipTone = "attention" | "destructive" | "working" | "neutral";
+/** The colour of a child dot, by the most urgent state among the descendants. */
+export type DotTone = "attention" | "destructive" | "working" | "unread";
 
-/** The tone of a chip whose most urgent rolled-up flag is `flag`. */
-export function chipTone(flag: Flag | null): ChipTone {
+export function dotTone(flag: Flag): DotTone {
   switch (flag) {
     case "waits-on-you":
+    case "offline":
       return "attention";
     case "unread-failed":
     case "queue-failed":
       return "destructive";
     case "working":
       return "working";
-    default:
-      return "neutral";
+    case "unread":
+      return "unread";
   }
 }
 

package/features/thread-list/model/toggles.ts

@@ -1,10 +1,10 @@
 // What a user's click on a chip, fold or header changes.
 // Pure: returns the preference patch and which auto-expand targets to drop.
 import type { Preferences } from "@/shared/preferences";
-import { ancestorsOf, type Family, type Forest } from "./families";
+import { ancestorsOf, type ThreadTree, type Forest } from "./trees";
 import { isGroupCollapsed, toggleGroupCollapse } from "./groups";
 import { isDoneUnseen } from "./state";
-import type { GroupView, OlderRow, ThreadRow } from "./view";
+import type { GroupView, OlderRow, SettledRow, ThreadRow } from "./view";
 
 export interface ToggleOutcome {
   patch: Partial<Preferences>;
@@ -29,36 +29,31 @@ export function toggleChip(row: ThreadRow, prefs: Preferences, forest: Forest):
     : openChildren(id, prefs);
 }
 
-/** Opens a parent's children, as its chip does: "+N more" in Needs attention and an auto-reveal's fold. */
+/** Opens a parent's children, as its chip does, from an auto-reveal's fold. */
 export function openChildren(parentId: string, prefs: Preferences): ToggleOutcome {
   return { patch: { expandedChildren: [...without(prefs.expandedChildren, parentId), parentId] }, drop: null };
 }
 
-export function toggleOlder(row: OlderRow, prefs: Preferences, group: GroupView | null, forest: Forest): ToggleOutcome {
+/** Opens or closes an open tree's "N more child threads" fold. */
+export function toggleOlder(row: OlderRow, prefs: Preferences, forest: Forest): ToggleOutcome {
   if (row.scope === "reveal") return openChildren(row.scopeId, prefs);
   if (!row.expanded) {
     return { patch: { expandedOlder: [...without(prefs.expandedOlder, row.scopeId), row.scopeId] }, drop: null };
   }
-  const patch = { expandedOlder: without(prefs.expandedOlder, row.scopeId) };
-  if (row.scope === "family") return { patch, drop: under(forest, row.scopeId) };
-  // Folding a group's older roots drops the targets that held it open.
-  const quietRoots = new Set<string>();
-  for (const family of forest.families) if (family.quietIgnoringOpen) quietRoots.add(family.root.thread.id);
-  const inGroup = new Set(group?.rootIds ?? []);
-  return {
-    patch,
-    drop: (id) => {
-      const family = forest.familyOf.get(id);
-      return family !== undefined && quietRoots.has(family.root.thread.id) && inGroup.has(family.root.thread.id);
-    },
-  };
+  return { patch: { expandedOlder: without(prefs.expandedOlder, row.scopeId) }, drop: under(forest, row.scopeId) };
+}
+
+/** Opens or closes a group's settled fold. */
+export function toggleSettled(row: SettledRow, prefs: Preferences): ToggleOutcome {
+  const rest = without(prefs.openSettledFolds, row.groupId);
+  return { patch: { openSettledFolds: row.expanded ? rest : [...rest, row.groupId] }, drop: null };
 }
 
 export function toggleGroup(group: GroupView, prefs: Preferences, forest: Forest): ToggleOutcome {
   const inGroup = new Set(group.rootIds);
   const dropGroup = (id: string) => {
-    const family = forest.familyOf.get(id);
-    return family !== undefined && inGroup.has(family.root.thread.id);
+    const tree = forest.treeOf.get(id);
+    return tree !== undefined && inGroup.has(tree.root.thread.id);
   };
   if (group.collapsed) {
     return {
@@ -78,19 +73,35 @@ export interface MarkAllRead {
   seen: string[];
 }
 
-/** Every unread thread in the families, descendants included. */
+/** Every unread thread in the trees, descendants included: Mark all read, and a root's Mark read for its tree. */
 export function markAllReadPlan(
-  families: readonly Family[],
+  trees: readonly ThreadTree[],
   context: { activeThreadId: string | null; finishedAt: Readonly<Record<string, number>>; seenAt: Readonly<Record<string, number>> },
 ): MarkAllRead {
   const read: string[] = [];
   const seen: string[] = [];
-  for (const family of families) {
-    for (const info of [family.root, ...family.descendants]) {
-      if (!info.unread || info.thread.isArchived) continue;
+  for (const tree of trees) {
+    for (const info of [tree.root, ...tree.descendants]) {
+      if (!info.unread) continue;
       read.push(info.thread.id);
       if (isDoneUnseen(info.thread, context)) seen.push(info.thread.id);
     }
   }
   return { read, seen };
 }
+
+/**
+ * What one row's Mark read marks: on a tree's root, every unread thread in
+ * the tree; on any other row, the thread alone.
+ */
+export function markReadPlanFor(
+  threadId: string,
+  forest: Pick<Forest, "infos" | "treeOf">,
+  context: { activeThreadId: string | null; finishedAt: Readonly<Record<string, number>>; seenAt: Readonly<Record<string, number>> },
+): MarkAllRead {
+  const tree = forest.treeOf.get(threadId);
+  if (tree !== undefined && tree.root.thread.id === threadId) return markAllReadPlan([tree], context);
+  const thread = forest.infos.get(threadId)?.thread;
+  if (thread === undefined) return { read: [threadId], seen: [] };
+  return { read: [threadId], seen: isDoneUnseen(thread, context) ? [threadId] : [] };
+}