Skip to content

The open-source app everyone uses to manage agents at work

fix(ui): defer Inbox re-sort to attention boundaries (#10623)

Dottaec84eb7342ed
diff --git a/ui/src/hooks/useInboxSortAttention.test.tsx b/ui/src/hooks/useInboxSortAttention.test.tsx
new file mode 100644
index 0000000000..b4016e0dd2
--- /dev/null
+++ b/ui/src/hooks/useInboxSortAttention.test.tsx
@@ -0,0 +1,175 @@
+// @vitest-environment jsdom
+
+import { useEffect } from "react";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+ INBOX_SORT_HIDDEN_COMMIT_MS,
+ INBOX_SORT_IDLE_COMMIT_MS,
+ type InboxSortAttention,
+ type InboxSortCommitReason,
+ useInboxSortAttention,
+} from "./useInboxSortAttention";
+
+type HarnessProps = {
+ viewIdentity: string;
+ onCommit: (reason: InboxSortCommitReason) => void;
+ onReady: (attention: InboxSortAttention) => void;
+};
+
+function Harness({ viewIdentity, onCommit, onReady }: HarnessProps) {
+ const attention = useInboxSortAttention({ viewIdentity, onCommit });
+ useEffect(() => onReady(attention), [attention, onReady]);
+ return null;
+}
+
+function setVisibility(state: "visible" | "hidden") {
+ Object.defineProperty(document, "visibilityState", {
+ configurable: true,
+ get: () => state,
+ });
+}
+
+function mountHook(viewIdentity = "mine:all:none") {
+ const container = document.createElement("div");
+ const root = createRoot(container);
+ const onCommit = vi.fn<(reason: InboxSortCommitReason) => void>();
+ let attention: InboxSortAttention | null = null;
+ const onReady = (value: InboxSortAttention) => {
+ attention = value;
+ };
+
+ const render = (nextViewIdentity = viewIdentity) => {
+ flushSync(() => {
+ root.render(
+ <Harness
+ viewIdentity={nextViewIdentity}
+ onCommit={onCommit}
+ onReady={onReady}
+ />,
+ );
+ });
+ };
+
+ render();
+ return {
+ onCommit,
+ render,
+ attention: () => {
+ if (!attention) throw new Error("Hook did not mount");
+ return attention;
+ },
+ unmount: () => flushSync(() => root.unmount()),
+ };
+}
+
+describe("useInboxSortAttention", () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ setVisibility("visible");
+ });
+
+ afterEach(() => {
+ vi.runOnlyPendingTimers();
+ vi.useRealTimers();
+ setVisibility("visible");
+ });
+
+ it("commits after the visible inbox is idle for the threshold", () => {
+ const hook = mountHook();
+ hook.onCommit.mockClear();
+
+ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS - 1);
+ expect(hook.onCommit).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(1);
+ expect(hook.onCommit).toHaveBeenCalledWith("idle");
+ hook.unmount();
+ });
+
+ it("keeps committing every interval while the inbox stays idle", () => {
+ const hook = mountHook();
+ hook.onCommit.mockClear();
+
+ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS);
+ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS);
+ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS);
+ // The idle timer re-arms after each fire, so a long-idle inbox never freezes
+ // at the first snapshot.
+ const idleCalls = hook.onCommit.mock.calls.filter(([reason]) => reason === "idle");
+ expect(idleCalls.length).toBe(3);
+ hook.unmount();
+ });
+
+ it("resets the idle threshold on inbox interaction", () => {
+ const hook = mountHook();
+ hook.onCommit.mockClear();
+
+ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS - 1_000);
+ hook.attention().noteInteraction();
+ vi.advanceTimersByTime(1_000);
+ expect(hook.onCommit).not.toHaveBeenCalled();
+
+ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS - 1_000);
+ expect(hook.onCommit).toHaveBeenCalledWith("idle");
+ hook.unmount();
+ });
+
+ it("commits after a long hide but not after a brief hide", () => {
+ const hook = mountHook();
+ hook.onCommit.mockClear();
+
+ setVisibility("hidden");
+ document.dispatchEvent(new Event("visibilitychange"));
+ vi.advanceTimersByTime(INBOX_SORT_HIDDEN_COMMIT_MS - 1);
+ setVisibility("visible");
+ document.dispatchEvent(new Event("visibilitychange"));
+ expect(hook.onCommit).not.toHaveBeenCalled();
+
+ setVisibility("hidden");
+ document.dispatchEvent(new Event("visibilitychange"));
+ vi.advanceTimersByTime(INBOX_SORT_HIDDEN_COMMIT_MS);
+ setVisibility("visible");
+ document.dispatchEvent(new Event("visibilitychange"));
+ expect(hook.onCommit).toHaveBeenCalledTimes(1);
+ expect(hook.onCommit).toHaveBeenCalledWith("visibility");
+ hook.unmount();
+ });
+
+ it("always commits when remounted", () => {
+ const first = mountHook();
+ expect(first.onCommit).toHaveBeenCalledWith("mount");
+ first.unmount();
+
+ const second = mountHook();
+ expect(second.onCommit).toHaveBeenCalledWith("mount");
+ second.unmount();
+ });
+
+ it("commits for tab, filter, and group-by identity changes", () => {
+ const hook = mountHook();
+ hook.onCommit.mockClear();
+
+ hook.render("assigned:open:project");
+ hook.render("assigned:closed:project");
+ hook.render("assigned:closed:assignee");
+ expect(hook.onCommit).toHaveBeenCalledTimes(3);
+ expect(hook.onCommit).toHaveBeenNthCalledWith(1, "view-identity-change");
+ expect(hook.onCommit).toHaveBeenNthCalledWith(2, "view-identity-change");
+ expect(hook.onCommit).toHaveBeenNthCalledWith(3, "view-identity-change");
+ hook.unmount();
+ });
+
+ it("always commits on manual refresh", () => {
+ const hook = mountHook();
+ hook.onCommit.mockClear();
+
+ hook.attention().commitManualRefresh();
+ hook.attention().commitManualRefresh();
+ expect(hook.onCommit).toHaveBeenCalledTimes(2);
+ expect(hook.onCommit).toHaveBeenNthCalledWith(1, "manual-refresh");
+ expect(hook.onCommit).toHaveBeenNthCalledWith(2, "manual-refresh");
+ hook.unmount();
+ });
+});
diff --git a/ui/src/hooks/useInboxSortAttention.ts b/ui/src/hooks/useInboxSortAttention.ts
new file mode 100644
index 0000000000..b6de99f0c1
--- /dev/null
+++ b/ui/src/hooks/useInboxSortAttention.ts
@@ -0,0 +1,127 @@
+import { useCallback, useEffect, useRef } from "react";
+
+export const INBOX_SORT_IDLE_COMMIT_MS = 150_000;
+export const INBOX_SORT_HIDDEN_COMMIT_MS = 30_000;
+
+export type InboxSortCommitReason =
+ | "mount"
+ | "idle"
+ | "visibility"
+ | "view-identity-change"
+ | "manual-refresh";
+
+type UseInboxSortAttentionOptions = {
+ viewIdentity: string;
+ onCommit: (reason: InboxSortCommitReason) => void;
+ idleCommitMs?: number;
+ hiddenCommitMs?: number;
+};
+
+export type InboxSortAttention = {
+ /** Call for pointer, keyboard, hover, archive, expand/collapse, or scroll activity. */
+ noteInteraction: () => void;
+ /** Commit immediately at an explicit refresh boundary. */
+ commitManualRefresh: () => void;
+};
+
+function isDocumentVisible(): boolean {
+ return typeof document === "undefined" || document.visibilityState === "visible";
+}
+
+/**
+ * Owns the attention boundaries at which the inbox may safely adopt a newly
+ * computed sort order. The caller owns order reconciliation and calls
+ * `noteInteraction` for activity scoped to the inbox list.
+ */
+export function useInboxSortAttention({
+ viewIdentity,
+ onCommit,
+ idleCommitMs = INBOX_SORT_IDLE_COMMIT_MS,
+ hiddenCommitMs = INBOX_SORT_HIDDEN_COMMIT_MS,
+}: UseInboxSortAttentionOptions): InboxSortAttention {
+ const onCommitRef = useRef(onCommit);
+ const idleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+ const hiddenAtRef = useRef<number | null>(null);
+ const committedInitialViewRef = useRef(false);
+ const previousViewIdentityRef = useRef(viewIdentity);
+
+ useEffect(() => {
+ onCommitRef.current = onCommit;
+ }, [onCommit]);
+
+ const clearIdleTimer = useCallback(() => {
+ if (idleTimerRef.current !== null) {
+ clearTimeout(idleTimerRef.current);
+ idleTimerRef.current = null;
+ }
+ }, []);
+
+ const restartIdleTimer = useCallback(() => {
+ clearIdleTimer();
+ if (!isDocumentVisible()) return;
+
+ // Re-arm after each idle commit so an inbox left untouched keeps adopting the
+ // freshly computed order every interval, rather than freezing at the first
+ // idle snapshot until the next interaction or attention boundary.
+ const armIdleTimer = () => {
+ idleTimerRef.current = setTimeout(() => {
+ idleTimerRef.current = null;
+ if (!isDocumentVisible()) return;
+ onCommitRef.current("idle");
+ armIdleTimer();
+ }, idleCommitMs);
+ };
+ armIdleTimer();
+ }, [clearIdleTimer, idleCommitMs]);
+
+ const noteInteraction = useCallback(() => {
+ restartIdleTimer();
+ }, [restartIdleTimer]);
+
+ const commitManualRefresh = useCallback(() => {
+ onCommitRef.current("manual-refresh");
+ restartIdleTimer();
+ }, [restartIdleTimer]);
+
+ useEffect(() => {
+ if (!committedInitialViewRef.current) {
+ committedInitialViewRef.current = true;
+ onCommitRef.current("mount");
+ } else if (previousViewIdentityRef.current !== viewIdentity) {
+ onCommitRef.current("view-identity-change");
+ }
+
+ previousViewIdentityRef.current = viewIdentity;
+ restartIdleTimer();
+ return clearIdleTimer;
+ }, [clearIdleTimer, restartIdleTimer, viewIdentity]);
+
+ useEffect(() => {
+ if (typeof document === "undefined") return;
+
+ if (document.visibilityState !== "visible") {
+ hiddenAtRef.current = Date.now();
+ clearIdleTimer();
+ }
+
+ const handleVisibilityChange = () => {
+ if (document.visibilityState !== "visible") {
+ hiddenAtRef.current = Date.now();
+ clearIdleTimer();
+ return;
+ }
+
+ const hiddenAt = hiddenAtRef.current;
+ hiddenAtRef.current = null;
+ if (hiddenAt !== null && Date.now() - hiddenAt >= hiddenCommitMs) {
+ onCommitRef.current("visibility");
+ }
+ restartIdleTimer();
+ };
+
+ document.addEventListener("visibilitychange", handleVisibilityChange);
+ return () => document.removeEventListener("visibilitychange", handleVisibilityChange);
+ }, [clearIdleTimer, hiddenCommitMs, restartIdleTimer]);
+
+ return { noteInteraction, commitManualRefresh };
+}
diff --git a/ui/src/lib/inboxArchiveCache.ts b/ui/src/lib/inboxArchiveCache.ts
index 92b185f936..1f8dd12ffa 100644
--- a/ui/src/lib/inboxArchiveCache.ts
+++ b/ui/src/lib/inboxArchiveCache.ts
@@ -5,7 +5,7 @@ import { queryKeys } from "./queryKeys";
export type InboxIssueCacheSnapshot = Array<readonly [QueryKey, Issue[] | undefined]>;
-const INBOX_ARCHIVE_CONFIRMATION_GRACE_MS = 5_000;
+export const INBOX_ARCHIVE_CONFIRMATION_GRACE_MS = 5_000;
const INBOX_ARCHIVE_MAX_GUARD_MS = 30_000;
const EMPTY_ARCHIVED_ISSUE_IDS: ReadonlySet<string> = new Set();
diff --git a/ui/src/lib/inboxOrderPin.test.ts b/ui/src/lib/inboxOrderPin.test.ts
new file mode 100644
index 0000000000..30d3269d26
--- /dev/null
+++ b/ui/src/lib/inboxOrderPin.test.ts
@@ -0,0 +1,230 @@
+import type { Approval, HeartbeatRun, Issue, JoinRequest } from "@paperclipai/shared";
+import { describe, expect, it } from "vitest";
+import {
+ getInboxWorkItemKey,
+ type InboxGroupedSection,
+ type InboxWorkItem,
+} from "./inbox";
+import { INBOX_ARCHIVE_CONFIRMATION_GRACE_MS } from "./inboxArchiveCache";
+import {
+ captureInboxOrderPin,
+ reconcileInboxOrderPin,
+} from "./inboxOrderPin";
+
+function issue(id: string, title = id): Issue {
+ return {
+ id,
+ title,
+ status: "todo",
+ } as Issue;
+}
+
+function issueItem(value: Issue, timestamp = 0): InboxWorkItem {
+ return { kind: "issue", issue: value, timestamp };
+}
+
+function section(
+ key: string,
+ items: Issue[],
+ childrenByIssueId: ReadonlyArray<readonly [string, Issue[]]> = [],
+): InboxGroupedSection {
+ return {
+ key,
+ label: key,
+ displayItems: items.map((item) => issueItem(item)),
+ childrenByIssueId: new Map(childrenByIssueId),
+ searchSection: "none",
+ };
+}
+
+function sectionKeys(sections: readonly InboxGroupedSection[]): string[] {
+ return sections.map((value) => value.key);
+}
+
+function workItemSection(key: string, displayItems: InboxWorkItem[]): InboxGroupedSection {
+ return {
+ key,
+ label: key,
+ displayItems,
+ childrenByIssueId: new Map(),
+ searchSection: "none",
+ };
+}
+
+function rowIds(value: InboxGroupedSection): string[] {
+ return value.displayItems.map((item) => item.kind === "issue" ? item.issue.id : "non-issue");
+}
+
+describe("inboxOrderPin", () => {
+ it("keeps a parent, its group, and neighboring groups in place when a child is archived", () => {
+ const parent = issue("parent");
+ const child = issue("child");
+ const neighbor = issue("neighbor");
+ const committed = [
+ section("parent-group", [parent], [[parent.id, [child]]]),
+ section("neighbor-group", [neighbor]),
+ ];
+ const pin = captureInboxOrderPin(committed);
+
+ const fresh = [
+ section("neighbor-group", [neighbor]),
+ section("parent-group", [parent], [[parent.id, []]]),
+ ];
+ const result = reconcileInboxOrderPin(pin, fresh, 100);
+
+ expect(sectionKeys(result.sections)).toEqual(["parent-group", "neighbor-group"]);
+ expect(rowIds(result.sections[0]!)).toEqual([parent.id]);
+ expect(result.sections[0]!.childrenByIssueId.get(parent.id)).toEqual([]);
+ });
+
+ it("removes a group in place when its last row is archived", () => {
+ const archived = issue("archived");
+ const neighbor = issue("neighbor");
+ const pin = captureInboxOrderPin([
+ section("archived-group", [archived]),
+ section("neighbor-group", [neighbor]),
+ ]);
+
+ const result = reconcileInboxOrderPin(
+ pin,
+ [section("neighbor-group", [neighbor])],
+ 200,
+ );
+
+ expect(sectionKeys(result.sections)).toEqual(["neighbor-group"]);
+ expect(rowIds(result.sections[0]!)).toEqual([neighbor.id]);
+ expect(result.pin.sections.map((value) => [value.key, value.missingSince])).toEqual([
+ ["archived-group", 200],
+ ["neighbor-group", null],
+ ]);
+ });
+
+ it("restores an archived row to its original position within the tombstone grace window", () => {
+ const first = issue("first");
+ const restored = issue("restored");
+ const last = issue("last");
+ const pin = captureInboxOrderPin([section("group", [first, restored, last])]);
+ const archived = reconcileInboxOrderPin(pin, [section("group", [last, first])], 1_000);
+
+ expect(rowIds(archived.sections[0]!)).toEqual([first.id, last.id]);
+
+ const undone = reconcileInboxOrderPin(
+ archived.pin,
+ [section("group", [last, restored, first])],
+ 1_000 + INBOX_ARCHIVE_CONFIRMATION_GRACE_MS - 1,
+ );
+
+ expect(rowIds(undone.sections[0]!)).toEqual([first.id, restored.id, last.id]);
+ expect(undone.pin.sections[0]!.rows.every((entry) => entry.missingSince === null)).toBe(true);
+ });
+
+ it("treats a row restored after the grace window as a new algorithmic insertion", () => {
+ const first = issue("first");
+ const expired = issue("expired");
+ const last = issue("last");
+ const pin = captureInboxOrderPin([section("group", [first, expired, last])]);
+ const archived = reconcileInboxOrderPin(pin, [section("group", [last, first])], 1_000);
+
+ const restored = reconcileInboxOrderPin(
+ archived.pin,
+ [section("group", [last, first, expired])],
+ 1_000 + INBOX_ARCHIVE_CONFIRMATION_GRACE_MS,
+ );
+
+ expect(rowIds(restored.sections[0]!)).toEqual([first.id, last.id, expired.id]);
+ });
+
+ it("inserts new rows and groups algorithmically without reordering existing entries", () => {
+ const first = issue("first");
+ const last = issue("last");
+ const inserted = issue("inserted");
+ const neighbor = issue("neighbor");
+ const newGroupItem = issue("new-group-item");
+ const pin = captureInboxOrderPin([
+ section("existing", [first, last]),
+ section("neighbor", [neighbor]),
+ ]);
+
+ const result = reconcileInboxOrderPin(
+ pin,
+ [
+ section("neighbor", [neighbor]),
+ section("new-group", [newGroupItem]),
+ section("existing", [last, inserted, first]),
+ ],
+ 300,
+ );
+
+ expect(sectionKeys(result.sections)).toEqual(["existing", "new-group", "neighbor"]);
+ expect(rowIds(result.sections[0]!)).toEqual([first.id, inserted.id, last.id]);
+ });
+
+ it("uses fresh row content while retaining the pinned order", () => {
+ const first = issue("first", "Old first");
+ const last = issue("last", "Old last");
+ const pin = captureInboxOrderPin([section("group", [first, last])]);
+ const freshLast = { ...last, title: "Updated last", status: "in_progress" } as Issue;
+ const freshFirst = { ...first, title: "Updated first", status: "blocked" } as Issue;
+
+ const result = reconcileInboxOrderPin(
+ pin,
+ [section("group", [freshLast, freshFirst])],
+ 400,
+ );
+
+ expect(rowIds(result.sections[0]!)).toEqual([first.id, last.id]);
+ expect(result.sections[0]!.displayItems[0]).toBeDefined();
+ expect(result.sections[0]!.displayItems[0]!.kind).toBe("issue");
+ expect(result.sections[0]!.displayItems[0]).toMatchObject({
+ issue: { title: "Updated first", status: "blocked" },
+ });
+ expect(result.sections[0]!.displayItems[1]).toMatchObject({
+ issue: { title: "Updated last", status: "in_progress" },
+ });
+ });
+
+ it("pins approval, failed-run, and join-request rows by their stable keys", () => {
+ const approval = {
+ kind: "approval",
+ timestamp: 3,
+ approval: { id: "approval", status: "pending" } as Approval,
+ } satisfies InboxWorkItem;
+ const failedRun = {
+ kind: "failed_run",
+ timestamp: 2,
+ run: { id: "run", status: "failed" } as HeartbeatRun,
+ } satisfies InboxWorkItem;
+ const joinRequest = {
+ kind: "join_request",
+ timestamp: 1,
+ joinRequest: { id: "join", status: "pending_approval" } as JoinRequest,
+ } satisfies InboxWorkItem;
+ const pin = captureInboxOrderPin([
+ workItemSection("mixed", [approval, failedRun, joinRequest]),
+ ]);
+
+ const result = reconcileInboxOrderPin(
+ pin,
+ [workItemSection("mixed", [
+ { ...joinRequest, timestamp: 4 },
+ { ...failedRun, timestamp: 5 },
+ {
+ ...approval,
+ timestamp: 6,
+ approval: { ...approval.approval, status: "approved" } as Approval,
+ },
+ ])],
+ 500,
+ );
+
+ expect(result.sections[0]!.displayItems.map(getInboxWorkItemKey)).toEqual([
+ "approval:approval",
+ "run:run",
+ "join:join",
+ ]);
+ expect(result.sections[0]!.displayItems[0]).toMatchObject({
+ timestamp: 6,
+ approval: { status: "approved" },
+ });
+ });
+});
diff --git a/ui/src/lib/inboxOrderPin.ts b/ui/src/lib/inboxOrderPin.ts
new file mode 100644
index 0000000000..db62c80515
--- /dev/null
+++ b/ui/src/lib/inboxOrderPin.ts
@@ -0,0 +1,242 @@
+import type { Issue } from "@paperclipai/shared";
+import {
+ getInboxWorkItemKey,
+ type InboxGroupedSection,
+ type InboxWorkItem,
+} from "./inbox";
+import { INBOX_ARCHIVE_CONFIRMATION_GRACE_MS } from "./inboxArchiveCache";
+
+export interface InboxPinnedKey {
+ key: string;
+ missingSince: number | null;
+}
+
+export interface InboxPinnedSectionOrder extends InboxPinnedKey {
+ rows: readonly InboxPinnedKey[];
+ childrenByIssueId: ReadonlyMap<string, readonly InboxPinnedKey[]>;
+}
+
+export interface InboxOrderPin {
+ sections: readonly InboxPinnedSectionOrder[];
+}
+
+export interface InboxOrderPinReconcileResult {
+ sections: InboxGroupedSection[];
+ pin: InboxOrderPin;
+}
+
+interface ReconciledKeys {
+ entries: InboxPinnedKey[];
+ retainedPinnedKeys: ReadonlySet<string>;
+ visibleKeys: string[];
+}
+
+function inboxOrderRowKey(item: InboxWorkItem): string {
+ return item.kind === "issue" ? item.issue.id : getInboxWorkItemKey(item);
+}
+
+function captureKeys(keys: Iterable<string>): InboxPinnedKey[] {
+ return Array.from(keys, (key) => ({ key, missingSince: null }));
+}
+
+function captureSection(section: InboxGroupedSection): InboxPinnedSectionOrder {
+ return {
+ key: section.key,
+ missingSince: null,
+ rows: captureKeys(section.displayItems.map(inboxOrderRowKey)),
+ childrenByIssueId: new Map(
+ Array.from(section.childrenByIssueId, ([issueId, children]) => [
+ issueId,
+ captureKeys(children.map((child) => child.id)),
+ ]),
+ ),
+ };
+}
+
+export function captureInboxOrderPin(
+ sections: readonly InboxGroupedSection[],
+): InboxOrderPin {
+ return { sections: sections.map(captureSection) };
+}
+
+function insertionIndexForVisiblePosition(
+ entries: readonly InboxPinnedKey[],
+ visibleKeys: ReadonlySet<string>,
+ visibleIndex: number,
+): number {
+ let seenVisible = 0;
+ for (let index = 0; index < entries.length; index += 1) {
+ if (seenVisible === visibleIndex) return index;
+ if (visibleKeys.has(entries[index]!.key)) seenVisible += 1;
+ }
+ return entries.length;
+}
+
+function reconcileKeys(
+ pinned: readonly InboxPinnedKey[],
+ freshKeys: readonly string[],
+ nowMs: number,
+): ReconciledKeys {
+ const freshKeySet = new Set(freshKeys);
+ const entries = pinned.flatMap((entry): InboxPinnedKey[] => {
+ if (freshKeySet.has(entry.key)) {
+ return entry.missingSince === null
+ || nowMs - entry.missingSince < INBOX_ARCHIVE_CONFIRMATION_GRACE_MS
+ ? [{ key: entry.key, missingSince: null }]
+ : [];
+ }
+
+ const missingSince = entry.missingSince ?? nowMs;
+ return nowMs - missingSince < INBOX_ARCHIVE_CONFIRMATION_GRACE_MS
+ ? [{ key: entry.key, missingSince }]
+ : [];
+ });
+ const retainedPinnedKeys = new Set(entries.map((entry) => entry.key));
+
+ const visibleKeys = new Set(
+ entries
+ .filter((entry) => entry.missingSince === null)
+ .map((entry) => entry.key),
+ );
+
+ freshKeys.forEach((key, freshIndex) => {
+ if (retainedPinnedKeys.has(key)) return;
+ const insertionIndex = insertionIndexForVisiblePosition(entries, visibleKeys, freshIndex);
+ entries.splice(insertionIndex, 0, { key, missingSince: null });
+ visibleKeys.add(key);
+ });
+
+ return {
+ entries,
+ retainedPinnedKeys,
+ visibleKeys: entries
+ .filter((entry) => entry.missingSince === null)
+ .map((entry) => entry.key),
+ };
+}
+
+function reconcileChildren(
+ pinned: ReadonlyMap<string, readonly InboxPinnedKey[]>,
+ fresh: ReadonlyMap<string, Issue[]>,
+ nowMs: number,
+): {
+ pin: ReadonlyMap<string, readonly InboxPinnedKey[]>;
+ display: Map<string, Issue[]>;
+} {
+ const parentIssueIds = new Set([...pinned.keys(), ...fresh.keys()]);
+ const nextPin = new Map<string, readonly InboxPinnedKey[]>();
+ const display = new Map<string, Issue[]>();
+
+ for (const parentIssueId of parentIssueIds) {
+ const freshChildren = fresh.get(parentIssueId) ?? [];
+ const freshChildById = new Map(freshChildren.map((child) => [child.id, child]));
+ const reconciled = reconcileKeys(
+ pinned.get(parentIssueId) ?? [],
+ freshChildren.map((child) => child.id),
+ nowMs,
+ );
+
+ if (reconciled.entries.length > 0) {
+ nextPin.set(parentIssueId, reconciled.entries);
+ }
+ if (fresh.has(parentIssueId)) {
+ display.set(
+ parentIssueId,
+ reconciled.visibleKeys.flatMap((key) => {
+ const child = freshChildById.get(key);
+ return child ? [child] : [];
+ }),
+ );
+ }
+ }
+
+ return { pin: nextPin, display };
+}
+
+function reconcileSection(
+ pinned: InboxPinnedSectionOrder | undefined,
+ fresh: InboxGroupedSection,
+ nowMs: number,
+): { pin: InboxPinnedSectionOrder; display: InboxGroupedSection } {
+ if (!pinned) {
+ return { pin: captureSection(fresh), display: fresh };
+ }
+
+ const freshItemByKey = new Map(
+ fresh.displayItems.map((item) => [inboxOrderRowKey(item), item]),
+ );
+ const rows = reconcileKeys(
+ pinned.rows,
+ fresh.displayItems.map(inboxOrderRowKey),
+ nowMs,
+ );
+ const children = reconcileChildren(pinned.childrenByIssueId, fresh.childrenByIssueId, nowMs);
+
+ return {
+ pin: {
+ key: fresh.key,
+ missingSince: null,
+ rows: rows.entries,
+ childrenByIssueId: children.pin,
+ },
+ display: {
+ ...fresh,
+ displayItems: rows.visibleKeys.flatMap((key) => {
+ const item = freshItemByKey.get(key);
+ return item ? [item] : [];
+ }),
+ childrenByIssueId: children.display,
+ },
+ };
+}
+
+/**
+ * Applies a previously committed Inbox order to freshly computed sections.
+ *
+ * `nowMs` is explicit so reconciliation remains pure. Callers should retain the
+ * returned pin between reconciliations and replace it with `captureInboxOrderPin`
+ * at an attention/refresh commit point.
+ */
+export function reconcileInboxOrderPin(
+ pinned: InboxOrderPin,
+ freshSections: readonly InboxGroupedSection[],
+ nowMs: number,
+): InboxOrderPinReconcileResult {
+ const freshSectionByKey = new Map(freshSections.map((section) => [section.key, section]));
+ const sections = reconcileKeys(
+ pinned.sections,
+ freshSections.map((section) => section.key),
+ nowMs,
+ );
+ const pinnedSectionByKey = new Map(pinned.sections.map((section) => [section.key, section]));
+ const reconciledByKey = new Map<string, ReturnType<typeof reconcileSection>>();
+
+ for (const freshSection of freshSections) {
+ reconciledByKey.set(
+ freshSection.key,
+ reconcileSection(
+ sections.retainedPinnedKeys.has(freshSection.key)
+ ? pinnedSectionByKey.get(freshSection.key)
+ : undefined,
+ freshSection,
+ nowMs,
+ ),
+ );
+ }
+
+ const nextPinnedSections = sections.entries.flatMap((entry): InboxPinnedSectionOrder[] => {
+ const reconciled = reconciledByKey.get(entry.key);
+ if (reconciled) return [{ ...reconciled.pin, missingSince: entry.missingSince }];
+ const previous = pinnedSectionByKey.get(entry.key);
+ return previous ? [{ ...previous, missingSince: entry.missingSince }] : [];
+ });
+
+ return {
+ sections: sections.visibleKeys.flatMap((key) => {
+ const freshSection = freshSectionByKey.get(key);
+ if (!freshSection) return [];
+ return [reconciledByKey.get(key)?.display ?? freshSection];
+ }),
+ pin: { sections: nextPinnedSections },
+ };
+}
diff --git a/ui/src/pages/Inbox.test.tsx b/ui/src/pages/Inbox.test.tsx
index 48a3deccea..69518d147f 100644
--- a/ui/src/pages/Inbox.test.tsx
+++ b/ui/src/pages/Inbox.test.tsx
@@ -631,6 +631,107 @@ describe("Inbox toolbar", () => {
}
});
+ it("holds the inbox order across a reordering poll, then re-sorts at an attention boundary (PAP-16015)", async () => {
+ routerMock.location.pathname = "/inbox/mine";
+ const base = new Date("2026-03-11T00:00:00.000Z").getTime();
+ const issueA = createIssue({
+ id: "issue-a",
+ identifier: "PAP-3001",
+ title: "Pin row A",
+ lastActivityAt: new Date(base + 3000),
+ });
+ const issueB = createIssue({
+ id: "issue-b",
+ identifier: "PAP-3002",
+ title: "Pin row B",
+ lastActivityAt: new Date(base + 2000),
+ });
+ const issueC = createIssue({
+ id: "issue-c",
+ identifier: "PAP-3003",
+ title: "Pin row C",
+ lastActivityAt: new Date(base + 1000),
+ });
+ apiMocks.issuesList.mockResolvedValue([issueA, issueB, issueC]);
+
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false, staleTime: 0, gcTime: 0 } },
+ });
+ const root = createRoot(container);
+
+ // Collapse each displayed row to its A/B/C identity so we can assert order.
+ const orderOf = () =>
+ [...container.querySelectorAll("[data-inbox-item]")].flatMap((row) => {
+ const text = row.textContent ?? "";
+ if (text.includes("Pin row A")) return ["A"];
+ if (text.includes("Pin row B")) return ["B"];
+ if (text.includes("Pin row C")) return ["C"];
+ return [];
+ });
+
+ const visibilityDescriptor = Object.getOwnPropertyDescriptor(document, "visibilityState");
+ const setVisibility = (state: DocumentVisibilityState) => {
+ Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });
+ };
+ let nowValue = base + 1_000_000;
+ const nowSpy = vi.spyOn(Date, "now").mockImplementation(() => nowValue);
+
+ try {
+ await act(async () => {
+ root.render(
+ <QueryClientProvider client={queryClient}>
+ <Inbox />
+ </QueryClientProvider>,
+ );
+ });
+ await vi.waitFor(() => {
+ expect(container.querySelectorAll("[data-inbox-item]").length).toBeGreaterThanOrEqual(3);
+ });
+ expect(orderOf()).toEqual(["A", "B", "C"]);
+
+ // A poll makes row C the most-recently-active: the fresh sort is now [C, A, B].
+ apiMocks.issuesList.mockResolvedValue([
+ { ...issueA },
+ { ...issueB },
+ { ...issueC, lastActivityAt: new Date(base + 9000) },
+ ]);
+ await act(async () => {
+ await queryClient.invalidateQueries();
+ });
+ await vi.waitFor(() => {
+ expect(container.textContent).toContain("Pin row C");
+ });
+
+ // No attention boundary has fired, so the displayed order is held, not reshuffled.
+ expect(orderOf()).toEqual(["A", "B", "C"]);
+
+ // The tab is hidden long enough to lose attention, then regains focus: that
+ // visibility boundary is a commit point, so the inbox adopts the fresh order.
+ await act(async () => {
+ setVisibility("hidden");
+ document.dispatchEvent(new Event("visibilitychange"));
+ });
+ nowValue += 31_000;
+ await act(async () => {
+ setVisibility("visible");
+ document.dispatchEvent(new Event("visibilitychange"));
+ });
+ await vi.waitFor(() => {
+ expect(orderOf()).toEqual(["C", "A", "B"]);
+ });
+ } finally {
+ nowSpy.mockRestore();
+ if (visibilityDescriptor) {
+ Object.defineProperty(document, "visibilityState", visibilityDescriptor);
+ } else {
+ setVisibility("visible");
+ }
+ act(() => {
+ root.unmount();
+ });
+ }
+ });
+
it("keeps other issue archive controls enabled while one archive is pending", async () => {
routerMock.location.pathname = "/inbox/mine";
const issueA = createIssue({ id: "issue-a", identifier: "PAP-1001", title: "First inbox row" });
diff --git a/ui/src/pages/Inbox.tsx b/ui/src/pages/Inbox.tsx
index b50aace18d..2cfa3569c3 100644
--- a/ui/src/pages/Inbox.tsx
+++ b/ui/src/pages/Inbox.tsx
@@ -173,6 +173,12 @@ import {
type InboxWorkItemGroupBy,
} from "../lib/inbox";
import { useDismissedInboxAlerts, useInboxDismissals, useReadInboxItems } from "../hooks/useInboxBadge";
+import { useInboxSortAttention } from "../hooks/useInboxSortAttention";
+import {
+ captureInboxOrderPin,
+ reconcileInboxOrderPin,
+ type InboxOrderPin,
+} from "../lib/inboxOrderPin";
const INBOX_HEARTBEAT_RUN_LIMIT = 200;
const INBOX_ISSUE_LIST_LIMIT = 500;
@@ -1379,7 +1385,7 @@ export function Inbox() {
return next;
});
}, [selectedCompanyId]);
- const groupedSections = useMemo<InboxGroupedSection[]>(() => [
+ const freshGroupedSections = useMemo<InboxGroupedSection[]>(() => [
...buildGroupedInboxSections(filteredWorkItems, groupBy, inboxWorkspaceGrouping, { nestingEnabled }),
...buildGroupedInboxSections(
getInboxWorkItems({ issues: archivedSearchIssues, approvals: [] }),
@@ -1402,6 +1408,79 @@ export function Inbox() {
nestingEnabled,
]);
+ // --- Order pinning (PAP-16015) ---
+ // The freshly computed sort is only *displayed* at attention boundaries. Between
+ // them we reconcile the fresh sections against the last committed order so that
+ // archiving mid-engagement (which drops rows from the caches, and can lower a
+ // parent's subtree-max sort ts) can no longer reshuffle the list under the
+ // cursor. New items still land at their algorithmic position; archived rows hold
+ // their slot for the 5s undo grace before collapsing. See `inboxOrderPin.ts`.
+ const orderPinRef = useRef<InboxOrderPin>({ sections: [] });
+ // Bumped by an attention commit to force `groupedSections` to adopt the fresh order.
+ const [orderCommitToken, setOrderCommitToken] = useState(0);
+ const orderCommitRequestedRef = useRef(false);
+ const commitInboxOrder = useCallback(() => {
+ orderCommitRequestedRef.current = true;
+ setOrderCommitToken((token) => token + 1);
+ }, []);
+
+ // Distinct view = distinct pin. Switching tab/filter/search/grouping resets the
+ // held order so we never carry one view's layout into another.
+ const inboxSortViewIdentity = useMemo(
+ () =>
+ JSON.stringify([
+ selectedCompanyId,
+ tab,
+ groupBy,
+ nestingEnabled,
+ normalizedSearchQuery,
+ allCategoryFilter,
+ allApprovalFilter,
+ issueFilters,
+ ]),
+ [
+ allApprovalFilter,
+ allCategoryFilter,
+ groupBy,
+ issueFilters,
+ nestingEnabled,
+ normalizedSearchQuery,
+ selectedCompanyId,
+ tab,
+ ],
+ );
+ // Adopt the fresh order in the SAME render the view identity changes, so a
+ // section key shared between the two views never briefly shows the previous
+ // view's order before the hook's passive commit effect runs.
+ const previousInboxSortViewIdentityRef = useRef(inboxSortViewIdentity);
+ if (previousInboxSortViewIdentityRef.current !== inboxSortViewIdentity) {
+ previousInboxSortViewIdentityRef.current = inboxSortViewIdentity;
+ orderCommitRequestedRef.current = true;
+ }
+
+ const groupedSections = useMemo<InboxGroupedSection[]>(() => {
+ const nowMs = Date.now();
+ // An attention boundary (or a view change) fired: adopt the fresh order
+ // wholesale and re-pin it.
+ if (orderCommitRequestedRef.current) {
+ orderCommitRequestedRef.current = false;
+ orderPinRef.current = captureInboxOrderPin(freshGroupedSections);
+ return freshGroupedSections;
+ }
+ const { sections, pin } = reconcileInboxOrderPin(orderPinRef.current, freshGroupedSections, nowMs);
+ orderPinRef.current = pin;
+ return sections;
+ // orderCommitToken forces re-adoption at a commit boundary; inboxSortViewIdentity
+ // forces it on a view change even when the fresh sections keep their identity.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [freshGroupedSections, inboxSortViewIdentity, orderCommitToken]);
+
+ const inboxSortAttention = useInboxSortAttention({
+ viewIdentity: inboxSortViewIdentity,
+ onCommit: commitInboxOrder,
+ });
+ const noteInboxSortInteraction = inboxSortAttention.noteInteraction;
+
const openCreateIssueForGroup = useCallback((group: InboxGroupedSection) => {
const defaults = buildInboxIssueGroupCreateDefaults(
group.key,
@@ -1654,13 +1733,14 @@ export function Inbox() {
const hoveredNavKeyRef = useRef<string | null>(null);
const setSelectedIndexFromPointer = useCallback((idx: number) => {
if (!pointerMovedSinceKeyNavRef.current) return;
+ noteInboxSortInteraction();
hoveredIndexRef.current = idx;
hoveredNavKeyRef.current = navEntryKey(flatNavItemsRef.current[idx]);
// Drop any keyboard selection band the moment the mouse takes over, so we
// never show two identical highlights at once. React bails out when the
// value is already -1, so continuous hovering triggers no re-render.
setSelectedIndex((prev) => (prev < 0 ? prev : -1));
- }, []);
+ }, [noteInboxSortInteraction]);
const invalidateInboxIssueQueryCaches = () => {
if (!selectedCompanyId) return;
@@ -1670,6 +1750,8 @@ export function Inbox() {
const archiveIssueMutation = useMutation({
mutationFn: (id: string) => issuesApi.archiveFromInbox(id),
onMutate: async (id) => {
+ // Keep the sort pinned: archiving is engagement, so defer any idle re-sort.
+ noteInboxSortInteraction();
setActionError(null);
setArchivingIssueIds((prev) => new Set(prev).add(id));
@@ -1810,6 +1892,7 @@ export function Inbox() {
}, [markItemRead]);
const handleArchiveNonIssue = useCallback((key: string) => {
+ noteInboxSortInteraction();
setArchivingNonIssueIds((prev) => new Set(prev).add(key));
setTimeout(() => {
if (key.startsWith("alert:")) {
@@ -1823,7 +1906,7 @@ export function Inbox() {
return next;
});
}, 200);
- }, [dismissAlert, dismissInboxItem]);
+ }, [dismissAlert, dismissInboxItem, noteInboxSortInteraction]);
const nonIssueUnreadState = (key: string): NonIssueUnreadState => {
if (!canArchiveFromTab) return null;
@@ -1973,6 +2056,9 @@ export function Inbox() {
const navCount = navItems.length;
if (navCount === 0) return;
+ // Any inbox keystroke (nav, archive, undo) is engagement: hold the sort.
+ noteInboxSortInteraction();
+
/** Resolve the nav entry at an index to an issue (for child entries) or work item. */
const resolveNavEntry = (idx: number): { issue?: Issue; item?: InboxWorkItem } => {
const entry = navItems[idx];
@@ -2115,7 +2201,7 @@ export function Inbox() {
};
window.addEventListener("keydown", handleKeyDown);
return () => window.removeEventListener("keydown", handleKeyDown);
- }, [issueLinkState, keyboardShortcutsEnabled]);
+ }, [issueLinkState, keyboardShortcutsEnabled, noteInboxSortInteraction]);
// Scroll selected item into view
useEffect(() => {
@@ -2544,7 +2630,12 @@ export function Inbox() {
<>
{showSeparatorBefore("work_items") && <Separator />}
<div>
- <div ref={listRef} className="overflow-hidden">
+ <div
+ ref={listRef}
+ className="overflow-hidden"
+ onPointerDownCapture={noteInboxSortInteraction}
+ onWheelCapture={noteInboxSortInteraction}
+ >
{(() => {
const renderInboxIssue = ({
issue,