Refine archive management UX across web and mobile

BRANCH_DETAILS.md

@@ -0,0 +1,41 @@
+# Archive Settings UX
+
+The settings Archive panel uses a dense layout so large archives remain scannable. The native mobile Archived Threads screen mirrors the same information hierarchy and behavior with mobile-native project sections, swipe actions, long-press menus, and header controls.
+
+Expected behavior:
+
+- Archived conversations are grouped by project, and each project group is collapsed by default.
+- The Archive panel fetches archived thread snapshots from all configured environments, not only environments that currently have active projects, so archived-only workspaces remain visible, while active rows returned in those snapshots remain excluded from archive content and empty-state counts.
+- Web project headers show environment labels whenever multiple environments are configured and keep a sole remote environment labeled, while a sole primary environment remains implicit. Native project sections show environment labels and the header controls can filter the archive to all environments or one configured environment.
+- Native Settings exposes `Archived Threads` in both local-only and T3 Connect-configured modes through a shared `General`, `Appearance`, `Beta`, `Archive`, and `App` tail, preserving that order while each mode keeps its own account and configuration controls. The native settings contract owns the `SettingsArchive` route name, link, and title plus the legacy `SettingsWaitlist` alias metadata, while the native stack keeps that distinct alias pointed at `SettingsAuth`.
+- The page includes a search box that filters archived thread titles across all projects case-insensitively. Multi-word searches match any term, rank exact phrase matches first, rank titles matching every term ahead of partial term matches, and auto-open matching project groups while search is active. Native incremental search updates the existing list without remounting it for every keystroke, preserving scroll position and transient row state.
+- Expanded project headers include sortable `Archived` and `Created` columns; clicking either header toggles ascending/descending order for the conversations inside each group, with `Archived` descending as the default.
+- Native project-section ordering follows the selected archive sort field and direction. Invalid archived timestamps fall back to the conversation's created timestamp for sorting and display on both surfaces.
+- Native row and bulk actions share collision-safe per-thread reservations and action-executor identity keys, reserve bulk targets before confirmation, expose busy state only after confirmation, disable overlapping swipe/menu controls while reserved, and distinguish rows skipped because the same thread action is already in progress from commands that actually fail.
+- Web row and project actions reserve collision-safe per-thread locks before confirmation, expose busy state only for the threads owned by actions that have started after confirmation, disable overlapping controls while mutations run, give explicit feedback for rejected duplicates, and refresh archived snapshots once after bulk attempts instead of between concurrent mutations.
+- Conversation rows show only the relative archived and created ages inline with the title by default. On web row hover or keyboard focus, those age labels fade out and icon-only unarchive/delete actions appear as a right-side overlay with tooltips, matching the sidebar and source-control list-row action pattern. Native rows keep both age columns visible and expose the same actions through swipe gestures and the standard long-press context menu.
+- Archived conversations can be deleted directly from the Archive panel without unarchiving first. Web delete actions respect the shared `confirmThreadDelete` client setting, while native keeps its standard guarded delete flow.
+- Project group context menus expose `unarchive all` and `delete all` actions. While search is active, those bulk actions apply to the visible matching archived conversations and use matching-specific menu labels; otherwise they apply to all archived conversations in the project. Delete confirmations respect `confirmThreadDelete` on web and remain explicitly guarded on native; unarchive bulk actions remain guarded on both surfaces, and partial failures surface as not-fully-completed feedback instead of implying every archived thread failed.
+- Archive grouping, search ranking, sort state, and project bulk-action concurrency live in `apps/web/src/components/settings/SettingsPanels.logic.ts` on web and `apps/mobile/src/features/archive/archivedThreadList.ts` on native so the dense Archive behavior stays covered without growing the React components. Project groups expose and reuse collision-safe keys so project ids containing separator characters do not collapse expansion state or React row identity. Bulk actions stop scheduling new work after thrown failures, wait for active workers to settle, preserve the completed success/failure/skipped outcome counts, show incomplete-operation feedback, and surface the underlying exception messages instead of only a generic aggregate error. The Archive surfaces refresh archived threads after bulk unarchive/delete attempts even when the action runner throws.
+- The user guide documents Archive as a reversible thread-lifecycle action, covers the web, desktop, and mobile controls and safeguards, and explains that search scopes project bulk actions to visible matches. The documentation index links the guide, and the encyclopedia defines the Archive term separately from permanent deletion.
+
+Primary files:
+
+- `apps/web/src/components/settings/ArchiveSettings.tsx`
+- `apps/web/src/components/settings/SettingsPanels.tsx`
+- `apps/web/src/components/settings/SettingsPanels.logic.ts`
+- `apps/mobile/src/Stack.tsx`
+- `apps/mobile/src/features/settings/SettingsRouteScreen.tsx`
+- `apps/mobile/src/features/settings/settingsContract.ts`
+- `apps/mobile/src/features/settings/settingsContract.test.ts`
+- `apps/mobile/src/features/archive/ArchivedThreadsRouteScreen.tsx`
+- `apps/mobile/src/features/archive/ArchivedThreadsScreen.tsx`
+- `apps/mobile/src/features/archive/archivedThreadList.ts`
+- `docs/user/archive.md`
+- `docs/reference/encyclopedia.md`
+- `docs/README.md`
+
+## Development Ports
+
+- Web: `5734`
+- Server/WebSocket: `13774`

apps/mobile/src/Stack.tsx

@@ -47,6 +47,10 @@ import { SettingsAuthRouteScreen } from "./features/settings/SettingsAuthRouteSc
 import { SettingsEnvironmentsRouteScreen } from "./features/settings/SettingsEnvironmentsRouteScreen";
 import { SettingsLegalRouteScreen } from "./features/settings/SettingsLegalRouteScreen";
 import { SettingsRouteScreen } from "./features/settings/SettingsRouteScreen";
+import {
+  SETTINGS_ARCHIVE_ROUTE_CONTRACT,
+  SETTINGS_WAITLIST_ALIAS_ROUTE_CONTRACT,
+} from "./features/settings/settingsContract";
 import { ShowcaseCaptureCoordinator } from "./features/showcase/ShowcaseCaptureCoordinator";
 import {
   SettingsLegalDocumentCloseHeaderButton,
@@ -160,11 +164,11 @@ const SettingsSheetStack = createNativeStackNavigator({
         title: "Add Environment",
       },
     }),
-    SettingsArchive: createNativeStackScreen({
+    [SETTINGS_ARCHIVE_ROUTE_CONTRACT.name]: createNativeStackScreen({
       screen: ArchivedThreadsRouteScreen,
-      linking: "archive",
+      linking: SETTINGS_ARCHIVE_ROUTE_CONTRACT.linking,
       options: {
-        title: "Archived Threads",
+        title: SETTINGS_ARCHIVE_ROUTE_CONTRACT.title,
       },
     }),
     SettingsAppearance: createNativeStackScreen({
@@ -188,12 +192,12 @@ const SettingsSheetStack = createNativeStackNavigator({
         title: "Sign in",
       },
     }),
-    SettingsWaitlist: createNativeStackScreen({
+    [SETTINGS_WAITLIST_ALIAS_ROUTE_CONTRACT.name]: createNativeStackScreen({
       // Keep the old deep link working after the Connect GA launch.
       screen: SettingsAuthRouteScreen,
-      linking: "waitlist",
+      linking: SETTINGS_WAITLIST_ALIAS_ROUTE_CONTRACT.linking,
       options: {
-        title: "Sign in",
+        title: SETTINGS_WAITLIST_ALIAS_ROUTE_CONTRACT.title,
       },
     }),
   },

apps/mobile/src/features/archive/ArchivedThreadsRouteScreen.tsx

@@ -2,27 +2,73 @@ import type { EnvironmentId } from "@t3tools/contracts";
 import * as Arr from "effect/Array";
 import * as Order from "effect/Order";
 import { useFocusEffect } from "@react-navigation/native";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { Alert, Platform } from "react-native";
 
+import { showConfirmDialog } from "../../components/ConfirmDialogHost";
 import { useSavedRemoteConnections } from "../../state/use-remote-environment-registry";
 import { useClerkSettingsSheetDetent } from "../cloud/ClerkSettingsSheetDetent";
 import { useArchivedThreadListActions } from "../home/useThreadListActions";
 import {
   ArchivedThreadsScreen,
   type ArchivedThreadsHeaderEnvironment,
 } from "./ArchivedThreadsScreen";
-import { buildArchivedThreadGroups, type ArchivedThreadSortOrder } from "./archivedThreadList";
 import {
-  refreshArchivedThreadsForEnvironment,
-  useArchivedThreadSnapshots,
-} from "./useArchivedThreadSnapshots";
+  archivedThreadActionExceptionDescription,
+  archivedThreadActionSummaryDescription,
+  buildArchivedThreadGroups,
+  parseArchivedThreadSearchInput,
+  releaseArchivedThreadActionLock,
+  runArchivedThreadActions,
+  tryAcquireArchivedThreadActionLock,
+  type ArchivedThreadSortState,
+} from "./archivedThreadList";
+import { useArchivedThreadSnapshots } from "./useArchivedThreadSnapshots";
+import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
+
+function confirmArchivedProjectAction(input: {
+  readonly title: string;
+  readonly message: string;
+  readonly confirmText: string;
+  readonly destructive?: boolean;
+}): Promise<boolean> {
+  return new Promise((resolve) => {
+    if (Platform.OS === "ios") {
+      Alert.alert(input.title, input.message, [
+        { text: "Cancel", style: "cancel", onPress: () => resolve(false) },
+        {
+          text: input.confirmText,
+          style: input.destructive ? "destructive" : "default",
+          onPress: () => resolve(true),
+        },
+      ]);
+      return;
+    }
+    showConfirmDialog({
+      title: input.title,
+      message: input.message,
+      confirmText: input.confirmText,
+      destructive: input.destructive,
+      onCancel: () => resolve(false),
+      onConfirm: () => resolve(true),
+    });
+  });
+}
 
 export function ArchivedThreadsRouteScreen() {
   const { expand } = useClerkSettingsSheetDetent();
   const { savedConnectionsById } = useSavedRemoteConnections();
   const [searchQuery, setSearchQuery] = useState("");
   const [selectedEnvironmentId, setSelectedEnvironmentId] = useState<EnvironmentId | null>(null);
-  const [sortOrder, setSortOrder] = useState<ArchivedThreadSortOrder>("newest");
+  const [sort, setSort] = useState<ArchivedThreadSortState>({
+    field: "archivedAt",
+    direction: "desc",
+  });
+  const reservedThreadKeysRef = useRef(new Set<string>());
+  const [reservedThreadKeys, setReservedThreadKeys] = useState<ReadonlySet<string>>(
+    () => new Set(),
+  );
+  const [busyThreadKeys, setBusyThreadKeys] = useState<ReadonlySet<string>>(() => new Set());
   const environments = useMemo<ReadonlyArray<ArchivedThreadsHeaderEnvironment>>(
     () =>
       Arr.sort(
@@ -40,33 +86,155 @@ export function ArchivedThreadsRouteScreen() {
     () => environments.map((environment) => environment.environmentId),
     [environments],
   );
-  const environmentLabels = useMemo(
-    () =>
-      Object.fromEntries(
-        environments.map((environment) => [environment.environmentId, environment.label]),
-      ),
-    [environments],
-  );
   const { error, isLoading, refresh, snapshots } = useArchivedThreadSnapshots(environmentIds);
+  const search = useMemo(() => parseArchivedThreadSearchInput(searchQuery), [searchQuery]);
   const groups = useMemo(
     () =>
       buildArchivedThreadGroups({
         snapshots,
-        environmentLabels,
         environmentId: selectedEnvironmentId,
-        searchQuery,
-        sortOrder,
+        search,
+        sort,
       }),
-    [environmentLabels, searchQuery, selectedEnvironmentId, snapshots, sortOrder],
+    [search, selectedEnvironmentId, snapshots, sort],
   );
-  const refreshChangedEnvironment = useCallback(
-    (thread: { readonly environmentId: EnvironmentId }) => {
-      refreshArchivedThreadsForEnvironment(thread.environmentId);
+  const { unarchiveThread, deleteThread } = useArchivedThreadListActions();
+  const tryReserveThreadActions = useCallback(
+    (
+      threads: ReadonlyArray<EnvironmentThreadShell>,
+    ): { readonly start: () => void; readonly finish: () => void } | null => {
+      const lock = tryAcquireArchivedThreadActionLock(reservedThreadKeysRef.current, threads);
+      if (!lock) {
+        Alert.alert(
+          "Archive action already in progress",
+          "Wait for the current archived thread action to finish.",
+        );
+        return null;
+      }
+      setReservedThreadKeys(new Set(reservedThreadKeysRef.current));
+      let started = false;
+      return {
+        start: () => {
+          if (started) return;
+          started = true;
+          setBusyThreadKeys((current) => {
+            const next = new Set(current);
+            for (const key of lock.keys) next.add(key);
+            return next;
+          });
+        },
+        finish: () => {
+          releaseArchivedThreadActionLock(reservedThreadKeysRef.current, lock);
+          setReservedThreadKeys(new Set(reservedThreadKeysRef.current));
+          if (!started) return;
+          setBusyThreadKeys((current) => {
+            const next = new Set(current);
+            for (const key of lock.keys) next.delete(key);
+            return next;
+          });
+        },
+      };
     },
     [],
   );
-  const { unarchiveThread, confirmDeleteThread } =
-    useArchivedThreadListActions(refreshChangedEnvironment);
+  const showSkippedActionFeedback = useCallback(() => {
+    Alert.alert(
+      "Archive action already in progress",
+      "Wait for the current archived thread action to finish.",
+    );
+  }, []);
+  const handleUnarchiveThread = useCallback(
+    async (thread: EnvironmentThreadShell) => {
+      const reservation = tryReserveThreadActions([thread]);
+      if (!reservation) return;
+      reservation.start();
+      try {
+        const result = await unarchiveThread(thread);
+        if (result === "skipped") showSkippedActionFeedback();
+      } finally {
+        reservation.finish();
+      }
+    },
+    [showSkippedActionFeedback, tryReserveThreadActions, unarchiveThread],
+  );
+  const handleDeleteThread = useCallback(
+    async (thread: EnvironmentThreadShell) => {
+      const reservation = tryReserveThreadActions([thread]);
+      if (!reservation) return;
+      try {
+        const confirmed = await confirmArchivedProjectAction({
+          title: "Delete thread?",
+          message: `“${thread.title}” will be permanently deleted, including its terminal history.`,
+          confirmText: "Delete",
+          destructive: true,
+        });
+        if (!confirmed) return;
+        reservation.start();
+        const result = await deleteThread(thread);
+        if (result === "skipped") showSkippedActionFeedback();
+      } finally {
+        reservation.finish();
+      }
+    },
+    [deleteThread, showSkippedActionFeedback, tryReserveThreadActions],
+  );
+  const handleProjectAction = useCallback(
+    async (
+      projectTitle: string,
+      threads: ReadonlyArray<EnvironmentThreadShell>,
+      scope: "all" | "matching",
+      action: "unarchive" | "delete",
+    ) => {
+      const reservation = tryReserveThreadActions(threads);
+      if (!reservation) return;
+      try {
+        const scopeLabel =
+          scope === "matching" ? "matching archived conversations" : "all archived conversations";
+        const actionLabel = action === "unarchive" ? "Unarchive" : "Delete";
+        const confirmed = await confirmArchivedProjectAction({
+          title: `${actionLabel} ${scopeLabel}?`,
+          message:
+            action === "unarchive"
+              ? `Restore ${threads.length} conversation${threads.length === 1 ? "" : "s"} from “${projectTitle}”?`
+              : `Permanently delete ${threads.length} conversation${threads.length === 1 ? "" : "s"} from “${projectTitle}”? This also clears their terminal history.`,
+          confirmText: actionLabel,
+          destructive: action === "delete",
+        });
+        if (!confirmed) return;
+
+        reservation.start();
+        try {
+          const summary = await runArchivedThreadActions(threads, (thread) =>
+            action === "unarchive"
+              ? unarchiveThread(thread, {
+                  reportFailure: false,
+                  refreshArchivedThreads: false,
+                })
+              : deleteThread(thread, {
+                  reportFailure: false,
+                  refreshArchivedThreads: false,
+                }),
+          );
+          if (summary.failed > 0 || summary.skipped > 0) {
+            Alert.alert(
+              `Archived threads not fully ${action === "unarchive" ? "unarchived" : "deleted"}`,
+              archivedThreadActionSummaryDescription(summary),
+            );
+          }
+        } catch (error) {
+          Alert.alert(
+            `Archived threads not fully ${action === "unarchive" ? "unarchived" : "deleted"}`,
+            archivedThreadActionExceptionDescription(error),
+          );
+        } finally {
+          refresh();
+        }
+      } finally {
+        reservation.finish();
+      }
+    },
+    [deleteThread, refresh, tryReserveThreadActions, unarchiveThread],
+  );
 
   useFocusEffect(
     useCallback(() => {
@@ -81,15 +249,20 @@ export function ArchivedThreadsRouteScreen() {
       error={error}
       groups={groups}
       isLoading={isLoading}
-      onDeleteThread={confirmDeleteThread}
+      onDeleteThread={(thread) => void handleDeleteThread(thread)}
       onEnvironmentChange={setSelectedEnvironmentId}
+      onProjectAction={(projectTitle, threads, scope, action) =>
+        void handleProjectAction(projectTitle, threads, scope, action)
+      }
       onRefresh={refresh}
       onSearchQueryChange={setSearchQuery}
-      onSortOrderChange={setSortOrder}
-      onUnarchiveThread={unarchiveThread}
+      onSortChange={setSort}
+      onUnarchiveThread={(thread) => void handleUnarchiveThread(thread)}
       searchQuery={searchQuery}
       selectedEnvironmentId={selectedEnvironmentId}
-      sortOrder={sortOrder}
+      sort={sort}
+      busyThreadKeys={busyThreadKeys}
+      reservedThreadKeys={reservedThreadKeys}
     />
   );
 }