@opengeni/react 4.2.1-canary.39642758903001 → 4.3.1

package/src/app/lib/actions/actions.test.ts

@@ -0,0 +1,249 @@
+import { describe, expect, test } from "bun:test";
+import {
+  applicableChords,
+  chordAccelerator,
+  chordAriaKeys,
+  chordKeys,
+  chordLabel,
+  matchesChord,
+  type Chord,
+} from "./chords";
+import type { ChatRecord } from "./chat-directory";
+import { isSwitcherKey, openChatSwitcher, stepChatSwitcher, SWITCHER_LIMIT } from "./chat-switcher";
+import { LOOSE_MATCH_BELOW, rankLabel, rankWithKeywords } from "./rank";
+import { APP_ACTIONS } from "./registry";
+
+function key(
+  code: string,
+  modifiers: Partial<{
+    meta: boolean;
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+    key: string;
+  }> = {},
+) {
+  return {
+    code,
+    key: modifiers.key ?? "",
+    metaKey: Boolean(modifiers.meta),
+    ctrlKey: Boolean(modifiers.ctrl),
+    shiftKey: Boolean(modifiers.shift),
+    altKey: Boolean(modifiers.alt),
+    repeat: false,
+    isComposing: false,
+  };
+}
+
+describe("chords", () => {
+  const newChat: Chord = { code: "KeyO", mod: true, shift: true };
+
+  test("⌘ on Mac and Ctrl elsewhere, exactly", () => {
+    expect(matchesChord(key("KeyO", { meta: true, shift: true }), newChat, "mac")).toBe(true);
+    expect(matchesChord(key("KeyO", { ctrl: true, shift: true }), newChat, "mac")).toBe(false);
+    expect(matchesChord(key("KeyO", { ctrl: true, shift: true }), newChat, "other")).toBe(true);
+    expect(matchesChord(key("KeyO", { meta: true, shift: true }), newChat, "other")).toBe(false);
+    // Extra modifiers are a different chord.
+    expect(matchesChord(key("KeyO", { meta: true, shift: true, alt: true }), newChat, "mac")).toBe(
+      false,
+    );
+    expect(matchesChord(key("KeyO", { meta: true }), newChat, "mac")).toBe(false);
+  });
+
+  test("punctuation matches the typed character on other layouts", () => {
+    const sheet: Chord = { code: "Slash", mod: true };
+    // US: the physical "/" key.
+    expect(matchesChord(key("Slash", { meta: true, key: "/" }), sheet, "mac")).toBe(true);
+    // Nordic: "/" is Shift+7.
+    expect(matchesChord(key("Digit7", { meta: true, shift: true, key: "/" }), sheet, "mac")).toBe(
+      true,
+    );
+    // Shift+7 that types something else is not the chord.
+    expect(matchesChord(key("Digit7", { meta: true, shift: true, key: "&" }), sheet, "mac")).toBe(
+      false,
+    );
+    // A chord that needs Shift only matches its physical key.
+    const copyLink: Chord = { code: "Comma", mod: true, shift: true };
+    expect(matchesChord(key("Comma", { meta: true, shift: true, key: "<" }), copyLink, "mac")).toBe(
+      true,
+    );
+    expect(matchesChord(key("KeyM", { meta: true, shift: true, key: "," }), copyLink, "mac")).toBe(
+      false,
+    );
+  });
+
+  test("held keys and input methods never fire", () => {
+    expect(
+      matchesChord({ ...key("KeyO", { meta: true, shift: true }), repeat: true }, newChat, "mac"),
+    ).toBe(false);
+    expect(
+      matchesChord(
+        { ...key("KeyO", { meta: true, shift: true }), isComposing: true },
+        newChat,
+        "mac",
+      ),
+    ).toBe(false);
+  });
+
+  test("shows each platform's notation", () => {
+    const toggle: Chord = { code: "KeyS", mod: true, control: true };
+    expect(chordKeys(toggle, "mac")).toEqual(["⌃", "⌘", "S"]);
+    expect(chordLabel({ code: "Comma", mod: true, shift: true }, "mac")).toBe("⇧⌘,");
+    expect(chordLabel({ code: "Comma", mod: true, shift: true }, "other")).toBe("Ctrl+Shift+,");
+    expect(chordLabel({ code: "ArrowUp", alt: true }, "mac")).toBe("⌥↑");
+    expect(chordAriaKeys({ code: "ArrowUp", alt: true }, "other")).toBe("Alt+ArrowUp");
+    expect(chordAccelerator({ code: "KeyP", mod: true, alt: true })).toBe("CmdOrCtrl+Alt+P");
+    expect(chordAccelerator(toggle)).toBe("Ctrl+CmdOrCtrl+S");
+  });
+
+  test("browser-reserved keys stay on desktop", () => {
+    const action = APP_ACTIONS.find((candidate) => candidate.id === "chat.new")!;
+    expect(applicableChords(action.chords, "web", "mac").map((chord) => chord.code)).toEqual([
+      "KeyO",
+    ]);
+    expect(applicableChords(action.chords, "desktop", "mac").map((chord) => chord.code)).toEqual([
+      "KeyN",
+      "KeyO",
+    ]);
+    const inbox = APP_ACTIONS.find((candidate) => candidate.id === "go.inbox")!;
+    // Ctrl+Shift+I opens developer tools in browsers on Windows and Linux.
+    expect(applicableChords(inbox.chords, "web", "other")).toEqual([]);
+    expect(applicableChords(inbox.chords, "desktop", "other")).toHaveLength(1);
+  });
+
+  test("no two actions share a chord on any surface", () => {
+    for (const surface of ["web", "desktop"] as const) {
+      for (const platform of ["mac", "other"] as const) {
+        const seen = new Map<string, string>();
+        for (const action of APP_ACTIONS) {
+          for (const chord of applicableChords(action.chords, surface, platform)) {
+            const label = chordLabel(chord, platform);
+            expect(seen.get(label) ?? action.id).toBe(action.id);
+            seen.set(label, action.id);
+          }
+        }
+      }
+    }
+  });
+});
+
+describe("ranking", () => {
+  test("prefix, then word start, then anywhere, then words in any order, then letters", () => {
+    const query = "deploy";
+    const prefix = rankLabel("Deploy the desktop app", query)!;
+    const wordStart = rankLabel("Fix deploy script", query)!;
+    const inside = rankLabel("Redeploying staging", query)!;
+    expect(prefix).toBeGreaterThan(wordStart);
+    expect(wordStart).toBeGreaterThan(inside);
+    const anyOrder = rankLabel("Fix the deploy script", "script fix")!;
+    expect(anyOrder).toBeLessThan(inside);
+    expect(anyOrder).toBeGreaterThan(rankLabel("Keyboard shortcuts", "kbsh")!);
+  });
+
+  test("ignores case and accents", () => {
+    expect(rankLabel("Møte om økonomi", "møte")).not.toBeNull();
+    expect(rankLabel("Café menu", "cafe")).not.toBeNull();
+    expect(rankLabel("ÅRSOPPGJØR", "årsopp")).not.toBeNull();
+  });
+
+  test("drops scattered letters", () => {
+    expect(rankLabel("A long title about many unrelated things", "zq")).toBeNull();
+    expect(rankLabel("Keyboard shortcuts", "kbsh")).not.toBeNull();
+    expect(rankLabel("Anything", "x")).toBeNull();
+    // Abbreviations start words; letters picked out of the middle of words don't.
+    expect(rankLabel("Refactor billing webhooks", "rbw")).not.toBeNull();
+    expect(rankLabel("Customer churn analysis", "rna")).toBeNull();
+  });
+
+  test("real matches outrank every letters-in-order guess", () => {
+    expect(rankLabel("Pin", "pin")!).toBeGreaterThanOrEqual(LOOSE_MATCH_BELOW);
+    expect(rankLabel("Fix the deploy script", "script fix")!).toBeGreaterThanOrEqual(
+      LOOSE_MATCH_BELOW,
+    );
+    expect(rankLabel("Postgres slow query investigation", "pin")!).toBeLessThan(LOOSE_MATCH_BELOW);
+  });
+
+  test("keywords find an action under another name, a little lower", () => {
+    const direct = rankWithKeywords("Copy link", ["share", "url"], "copy")!;
+    const byKeyword = rankWithKeywords("Copy link", ["share", "url"], "share")!;
+    expect(byKeyword).not.toBeNull();
+    expect(byKeyword).toBeLessThan(direct);
+  });
+});
+
+describe("chat switcher", () => {
+  const record = (id: string, extra: Partial<ChatRecord> = {}): ChatRecord => ({
+    id,
+    workspaceId: "w",
+    title: id,
+    updatedAt: 1,
+    pinned: false,
+    archived: false,
+    row: null,
+    ...extra,
+  });
+  const directory = (recent: string[], records: ChatRecord[] = recent.map((id) => record(id))) => ({
+    recent,
+    rows: new Map(records.map((item) => [item.id, item])),
+  });
+
+  test("a press from a chat goes to the previous chat, and back again", () => {
+    const first = openChatSwitcher(directory(["a", "b", "c"]), "a", false)!;
+    expect(first.ids).toEqual(["a", "b", "c"]);
+    expect(first.ids[first.index]).toBe("b");
+    // Opening b moves it to the front, so the next press returns to a.
+    const second = openChatSwitcher(directory(["b", "a", "c"]), "b", false)!;
+    expect(second.ids[second.index]).toBe("a");
+  });
+
+  test("holding Control and pressing Tab walks down and wraps; Shift walks back", () => {
+    let state = openChatSwitcher(directory(["a", "b", "c"]), "a", false)!;
+    state = stepChatSwitcher(state, 1);
+    expect(state.ids[state.index]).toBe("c");
+    expect(state.visible).toBe(true);
+    state = stepChatSwitcher(state, 1);
+    expect(state.ids[state.index]).toBe("a");
+    state = stepChatSwitcher(state, -1);
+    expect(state.ids[state.index]).toBe("c");
+  });
+
+  test("Shift+Control+Tab starts at the oldest chat", () => {
+    const state = openChatSwitcher(directory(["a", "b", "c"]), "a", true)!;
+    expect(state.ids[state.index]).toBe("c");
+  });
+
+  test("away from a chat the most recent chat is the target", () => {
+    const state = openChatSwitcher(directory(["a", "b"]), null, false)!;
+    expect(state.ids[state.index]).toBe("a");
+  });
+
+  test("the open chat leads even before its visit is recorded", () => {
+    const state = openChatSwitcher(directory(["a", "b"]), "x", false)!;
+    expect(state.ids).toEqual(["x", "a", "b"]);
+    expect(state.ids[state.index]).toBe("a");
+  });
+
+  test("archived and subagent chats are left out, and nothing opens with nowhere to go", () => {
+    const rows = [
+      record("a"),
+      record("old", { archived: true }),
+      record("child", { row: { parentSessionId: "a" } as ChatRecord["row"] }),
+    ];
+    expect(openChatSwitcher(directory(["a", "old", "child"], rows), "a", false)).toBeNull();
+    expect(openChatSwitcher(directory([]), null, false)).toBeNull();
+  });
+
+  test("the list stops at ten chats", () => {
+    const ids = Array.from({ length: 15 }, (_, index) => `c${index}`);
+    expect(openChatSwitcher(directory(ids), "c0", false)!.ids).toHaveLength(SWITCHER_LIMIT);
+  });
+
+  test("only Control+Tab opens it", () => {
+    const tab = { code: "Tab", ctrlKey: true, metaKey: false, altKey: false };
+    expect(isSwitcherKey(tab)).toBe(true);
+    expect(isSwitcherKey({ ...tab, metaKey: true })).toBe(false);
+    expect(isSwitcherKey({ ...tab, altKey: true })).toBe(false);
+    expect(isSwitcherKey({ ...tab, ctrlKey: false })).toBe(false);
+    expect(isSwitcherKey({ ...tab, code: "KeyQ" })).toBe(false);
+  });
+});

package/src/app/lib/actions/chat-directory.ts

@@ -0,0 +1,231 @@
+/**
+ * What the app already knows about chats, so the command menu can answer
+ * instantly: rows the sidebar has loaded, the chats someone opened recently
+ * (kept across reloads), and the sidebar's visible order for next and previous
+ * chat. It is a cache for speed, never a source of authority: opening a chat
+ * still goes through the normal authorized reads.
+ */
+import { useSyncExternalStore } from "react";
+import { sessionDisplayTitle, type SessionListRow } from "../../../session-list-model";
+
+export type ChatRecord = {
+  id: string;
+  workspaceId: string;
+  title: string;
+  updatedAt: number;
+  pinned: boolean;
+  archived: boolean;
+  /** Present when the app holds a full or list row, needed for pin and archive. */
+  row: SessionListRow | null;
+};
+
+type DirectoryState = {
+  rows: Map<string, ChatRecord>;
+  /** Recently opened chat ids, most recent first. */
+  recent: string[];
+  /** Sidebar order of visible chats (pinned first), for next and previous. */
+  sidebarOrder: string[];
+  pinnedOrder: string[];
+  version: number;
+};
+
+const RECENT_LIMIT = 30;
+const directories = new Map<string, DirectoryState>();
+const listeners = new Map<string, Set<() => void>>();
+
+function key(subjectId: string, workspaceId: string): string {
+  return `${subjectId}\u0000${workspaceId}`;
+}
+
+function storageKey(subjectId: string, workspaceId: string): string {
+  return `opengeni.recentChats.${subjectId}.${workspaceId}`;
+}
+
+type StoredRecent = { id: string; title: string; at: number };
+
+function readStoredRecent(subjectId: string, workspaceId: string): StoredRecent[] {
+  if (typeof window === "undefined") return [];
+  try {
+    const raw = window.localStorage.getItem(storageKey(subjectId, workspaceId));
+    const parsed: unknown = raw ? JSON.parse(raw) : [];
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (item): item is StoredRecent =>
+        typeof item === "object" &&
+        item !== null &&
+        typeof (item as StoredRecent).id === "string" &&
+        typeof (item as StoredRecent).title === "string" &&
+        typeof (item as StoredRecent).at === "number",
+    );
+  } catch {
+    return [];
+  }
+}
+
+function directory(subjectId: string, workspaceId: string): DirectoryState {
+  const id = key(subjectId, workspaceId);
+  let state = directories.get(id);
+  if (!state) {
+    const stored = readStoredRecent(subjectId, workspaceId);
+    state = {
+      rows: new Map(
+        stored.map((item) => [
+          item.id,
+          {
+            id: item.id,
+            workspaceId,
+            title: item.title,
+            updatedAt: item.at,
+            pinned: false,
+            archived: false,
+            row: null,
+          },
+        ]),
+      ),
+      recent: stored.map((item) => item.id),
+      sidebarOrder: [],
+      pinnedOrder: [],
+      version: 0,
+    };
+    directories.set(id, state);
+  }
+  return state;
+}
+
+function emit(subjectId: string, workspaceId: string): void {
+  const state = directory(subjectId, workspaceId);
+  state.version += 1;
+  for (const listener of listeners.get(key(subjectId, workspaceId)) ?? []) listener();
+}
+
+function persistRecent(subjectId: string, workspaceId: string, state: DirectoryState): void {
+  if (typeof window === "undefined") return;
+  const stored: StoredRecent[] = state.recent.flatMap((id) => {
+    const record = state.rows.get(id);
+    return record ? [{ id, title: record.title, at: record.updatedAt }] : [];
+  });
+  try {
+    window.localStorage.setItem(storageKey(subjectId, workspaceId), JSON.stringify(stored));
+  } catch {
+    // Storage full or blocked: recent chats then last only for this page.
+  }
+}
+
+export function chatRecordFromRow(row: SessionListRow): ChatRecord {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    title: sessionDisplayTitle(row),
+    updatedAt: Date.parse(row.updatedAt) || 0,
+    pinned: Boolean(row.pinned),
+    archived: Boolean(row.archived),
+    row,
+  };
+}
+
+/** Remember rows the app has read (sidebar pages, search results, the open chat). */
+export function rememberChats(
+  subjectId: string,
+  workspaceId: string,
+  rows: readonly SessionListRow[],
+): void {
+  if (rows.length === 0) return;
+  const state = directory(subjectId, workspaceId);
+  let changed = false;
+  for (const row of rows) {
+    if (row.workspaceId !== workspaceId) continue;
+    const next = chatRecordFromRow(row);
+    const current = state.rows.get(row.id);
+    if (
+      current?.row === row ||
+      (current &&
+        current.row &&
+        current.title === next.title &&
+        current.updatedAt === next.updatedAt &&
+        current.pinned === next.pinned &&
+        current.archived === next.archived)
+    ) {
+      continue;
+    }
+    state.rows.set(row.id, next);
+    changed = true;
+  }
+  if (changed) emit(subjectId, workspaceId);
+}
+
+/** The chat was opened: move it to the front of the recent list. */
+export function recordChatVisit(subjectId: string, workspaceId: string, row: SessionListRow): void {
+  const state = directory(subjectId, workspaceId);
+  const record = { ...chatRecordFromRow(row), updatedAt: Date.now() };
+  const previous = state.rows.get(row.id);
+  state.rows.set(row.id, previous?.row && !record.row ? { ...previous, ...record } : record);
+  if (state.recent[0] !== row.id) {
+    state.recent = [row.id, ...state.recent.filter((id) => id !== row.id)].slice(0, RECENT_LIMIT);
+  }
+  persistRecent(subjectId, workspaceId, state);
+  emit(subjectId, workspaceId);
+}
+
+/** A chat was deleted or is no longer reachable: forget it. */
+export function forgetChat(subjectId: string, workspaceId: string, chatId: string): void {
+  const state = directory(subjectId, workspaceId);
+  if (!state.rows.delete(chatId) && !state.recent.includes(chatId)) return;
+  state.recent = state.recent.filter((id) => id !== chatId);
+  persistRecent(subjectId, workspaceId, state);
+  emit(subjectId, workspaceId);
+}
+
+/** The sidebar reports the chats it shows, in order, so next and previous follow it. */
+export function setSidebarOrder(
+  subjectId: string,
+  workspaceId: string,
+  order: readonly string[],
+  pinnedOrder: readonly string[],
+): void {
+  const state = directory(subjectId, workspaceId);
+  if (
+    state.sidebarOrder.length === order.length &&
+    state.sidebarOrder.every((id, index) => id === order[index]) &&
+    state.pinnedOrder.length === pinnedOrder.length &&
+    state.pinnedOrder.every((id, index) => id === pinnedOrder[index])
+  ) {
+    return;
+  }
+  state.sidebarOrder = [...order];
+  state.pinnedOrder = [...pinnedOrder];
+  emit(subjectId, workspaceId);
+}
+
+export type ChatDirectorySnapshot = Readonly<{
+  rows: ReadonlyMap<string, ChatRecord>;
+  recent: readonly string[];
+  sidebarOrder: readonly string[];
+  pinnedOrder: readonly string[];
+  version: number;
+}>;
+
+export function readChatDirectory(subjectId: string, workspaceId: string): ChatDirectorySnapshot {
+  return directory(subjectId, workspaceId);
+}
+
+function subscribe(subjectId: string, workspaceId: string, listener: () => void): () => void {
+  const id = key(subjectId, workspaceId);
+  let set = listeners.get(id);
+  if (!set) {
+    set = new Set();
+    listeners.set(id, set);
+  }
+  set.add(listener);
+  return () => {
+    set.delete(listener);
+  };
+}
+
+/** Re-renders when the directory changes; read the snapshot through `readChatDirectory`. */
+export function useChatDirectoryVersion(subjectId: string, workspaceId: string): number {
+  return useSyncExternalStore(
+    (listener) => subscribe(subjectId, workspaceId, listener),
+    () => directory(subjectId, workspaceId).version,
+    () => 0,
+  );
+}

package/src/app/lib/actions/chat-operations.ts

@@ -0,0 +1,145 @@
+/**
+ * The chat operations every surface shares: the command menu, chords, the
+ * chat header and the sidebar's row menus all copy links, pin, archive and
+ * mark chats through these, so they behave identically everywhere.
+ */
+import { useCallback, useMemo, useRef } from "react";
+import type { SessionListRow } from "../../../session-list-model";
+import { useAppContext } from "../../app-context";
+import { usePage } from "../navigation";
+import { applySessionArchiveProjection } from "../session-pagination";
+import { notifySessionListChanged } from "../session-list-invalidation";
+import { toast } from "../toast";
+
+export type ChatOperations = {
+  /** The chat's shareable address. */
+  linkTo(chat: Pick<SessionListRow, "id" | "workspaceId">): string;
+  copyLink(chat: Pick<SessionListRow, "id" | "workspaceId">): Promise<void>;
+  setPinned(chat: SessionListRow, pinned: boolean): Promise<void>;
+  setArchived(chat: SessionListRow, archived: boolean): Promise<void>;
+  setUnread(chat: SessionListRow, unread: boolean): Promise<void>;
+};
+
+export function chatPath(chat: Pick<SessionListRow, "id" | "workspaceId">): string {
+  return `/workspaces/${encodeURIComponent(chat.workspaceId)}/sessions/${encodeURIComponent(chat.id)}`;
+}
+
+async function writeClipboard(text: string): Promise<void> {
+  if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) {
+    await navigator.clipboard.writeText(text);
+    return;
+  }
+  // Older embeds without the async clipboard: a hidden textarea and execCommand.
+  const area = document.createElement("textarea");
+  area.value = text;
+  area.setAttribute("readonly", "");
+  area.style.position = "fixed";
+  area.style.opacity = "0";
+  document.body.append(area);
+  area.select();
+  const copied = document.execCommand("copy");
+  area.remove();
+  if (!copied) throw new Error("The browser blocked copying.");
+}
+
+export function useChatOperations(): ChatOperations {
+  const context = useAppContext();
+  const page = usePage();
+  const archiving = useRef(new Set<string>());
+  const linkTo = useCallback(
+    (chat: Pick<SessionListRow, "id" | "workspaceId">) => `${page.origin()}${chatPath(chat)}`,
+    [page],
+  );
+  const copyLink = useCallback(
+    async (chat: Pick<SessionListRow, "id" | "workspaceId">) => {
+      try {
+        await writeClipboard(linkTo(chat));
+        toast.success("Link copied");
+      } catch (error) {
+        toast.error("Couldn't copy the link.", {
+          description: error instanceof Error ? error.message : String(error),
+        });
+      }
+    },
+    [linkTo],
+  );
+  const setPinned = useCallback(
+    async (chat: SessionListRow, pinned: boolean) => {
+      const updated = await context.updateSessionPin(
+        chat.workspaceId,
+        chat.id,
+        pinned,
+        chat.pinVersion ?? 0,
+      );
+      if (updated) toast.success(pinned ? "Chat pinned" : "Chat unpinned");
+      else toast.error(pinned ? "Couldn't pin the chat." : "Couldn't unpin the chat.");
+    },
+    [context],
+  );
+  const setArchived = useCallback(
+    async (chat: SessionListRow, archived: boolean) => {
+      if (archiving.current.has(chat.id)) return;
+      const accepted = context.captureWorkspaceInvocation(chat.workspaceId);
+      if (!accepted) return;
+      archiving.current.add(chat.id);
+      try {
+        const updated = await context.client.updateSessionArchive(chat.workspaceId, chat.id, {
+          archived,
+          expectedVersion: chat.archiveVersion ?? 0,
+        });
+        if (!context.ownsWorkspaceInvocation(chat.workspaceId, accepted)) return;
+        context.setSession((current) =>
+          current?.id === updated.id && current.workspaceId === updated.workspaceId
+            ? applySessionArchiveProjection(current, updated)
+            : current,
+        );
+        notifySessionListChanged({
+          workspaceId: chat.workspaceId,
+          sessionId: chat.id,
+          archived: updated.archived,
+        });
+        toast.success(updated.archived ? "Chat archived." : "Chat restored.");
+      } catch (error) {
+        if (!context.ownsWorkspaceInvocation(chat.workspaceId, accepted)) return;
+        toast.error(archived ? "Couldn't archive the chat." : "Couldn't restore the chat.", {
+          description: error instanceof Error ? error.message : String(error),
+        });
+      } finally {
+        archiving.current.delete(chat.id);
+      }
+    },
+    [context],
+  );
+  const setUnread = useCallback(
+    async (chat: SessionListRow, unread: boolean) => {
+      try {
+        const updated = await context.client.updateSessionAttention(chat.workspaceId, chat.id, {
+          unread,
+          expectedVersion: chat.attentionVersion ?? 0,
+        });
+        context.setSession((current) =>
+          current?.id === updated.id
+            ? {
+                ...current,
+                ...(updated.unread !== undefined ? { unread: updated.unread } : {}),
+                ...(updated.attentionVersion !== undefined
+                  ? { attentionVersion: updated.attentionVersion }
+                  : {}),
+              }
+            : current,
+        );
+        notifySessionListChanged({ workspaceId: chat.workspaceId, sessionId: chat.id });
+        toast.success(unread ? "Marked as unread" : "Marked as read");
+      } catch (error) {
+        toast.error("Couldn't update the chat.", {
+          description: error instanceof Error ? error.message : String(error),
+        });
+      }
+    },
+    [context],
+  );
+  return useMemo(
+    () => ({ linkTo, copyLink, setPinned, setArchived, setUnread }),
+    [linkTo, copyLink, setPinned, setArchived, setUnread],
+  );
+}

package/src/app/lib/actions/chat-switcher.ts

@@ -0,0 +1,62 @@
+/**
+ * Control+Tab in the desktop app: switch between recently viewed chats, most
+ * recent first, as ⌘Tab switches apps. A quick press goes back to the previous
+ * chat (press again to return); holding Control shows the list, each Tab moves
+ * down it (Shift+Tab up), and releasing Control opens the highlighted chat.
+ *
+ * The list is read once when the switcher opens, so it holds still while the
+ * person cycles through it.
+ */
+import type { ChatDirectorySnapshot } from "./chat-directory";
+
+/** At most this many chats; older ones are a search away in ⌘K. */
+export const SWITCHER_LIMIT = 10;
+/** A press shorter than this switches without ever drawing the list. */
+export const SWITCHER_SHOW_DELAY_MS = 140;
+
+export type ChatSwitcherState = Readonly<{
+  /** Chats in the order shown, most recently viewed first. */
+  ids: readonly string[];
+  /** The highlighted chat. */
+  index: number;
+  /** Whether the list is drawn (after the delay, or once Tab is pressed again). */
+  visible: boolean;
+}>;
+
+/**
+ * The chats to switch between, most recently viewed first, with the open chat
+ * (when there is one) at the front. Null when there is nowhere to switch to.
+ */
+export function openChatSwitcher(
+  directory: Pick<ChatDirectorySnapshot, "recent" | "rows">,
+  currentChatId: string | null,
+  backwards: boolean,
+): ChatSwitcherState | null {
+  const switchable = directory.recent.filter((id) => {
+    const record = directory.rows.get(id);
+    if (!record || record.archived) return false;
+    // Subagent chats live under their parent, as in the sidebar.
+    return !record.row || record.row.parentSessionId === null;
+  });
+  const ids = currentChatId
+    ? [currentChatId, ...switchable.filter((id) => id !== currentChatId)]
+    : switchable;
+  const limited = ids.slice(0, SWITCHER_LIMIT);
+  // Away from a chat (the inbox, a new chat) the most recent chat is the target.
+  const first = currentChatId ? 1 : 0;
+  if (limited.length <= first) return null;
+  return { ids: limited, index: backwards ? limited.length - 1 : first, visible: false };
+}
+
+/** Tab moves down the list and Shift+Tab up, wrapping at the ends. */
+export function stepChatSwitcher(state: ChatSwitcherState, step: 1 | -1): ChatSwitcherState {
+  const count = state.ids.length;
+  return { ...state, index: (state.index + step + count) % count, visible: true };
+}
+
+/** Control+Tab exactly: no ⌘, no ⌥ (Shift reverses). */
+export function isSwitcherKey(
+  event: Pick<KeyboardEvent, "code" | "ctrlKey" | "metaKey" | "altKey">,
+) {
+  return event.code === "Tab" && event.ctrlKey && !event.metaKey && !event.altKey;
+}