@kabmo-labs/kabmo 0.0.1 → 0.2.0

package/src/client/components/layout/session-sidebar/SessionItem.batch.test.ts

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The row's batch-mode switch, on both layouts.
+ *
+ * Two properties decide whether the feature is usable at all: in select mode a
+ * click must TOGGLE the selection rather than open the session (otherwise the
+ * checkbox is decorative and every tap navigates away), and the row's own
+ * actions must be gone (an action beside a checkbox is a second thing the click
+ * could mean). The rows draw these from one prop set, so both layouts are
+ * asserted here rather than trusted to match.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+
+import { SessionItem } from '@/client/components/layout/session-sidebar/SessionItem';
+import type { SessionItemProps } from '@/client/components/layout/session-sidebar/SessionItem';
+import { MobileSessionRow } from '@/client/components/mobile/mobile-session-sidebar/SessionRow';
+import type { MobileSessionRowProps } from '@/client/components/mobile/mobile-session-sidebar/SessionRow';
+import type { SessionItemData } from '@/shared/types';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'HTMLInputElement', 'Event', 'MouseEvent', 'KeyboardEvent'] as const;
+const nativeGlobals: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+
+let container: HTMLElement;
+
+beforeAll(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in nativeGlobals)) nativeGlobals[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (nativeGlobals[key] === undefined) delete target[key];
+    else target[key] = nativeGlobals[key];
+  }
+});
+
+afterEach(() => {
+  container?.remove();
+});
+
+async function mountDesktop(overrides: Partial<SessionItemProps> = {}) {
+  const calls = { click: 0, toggle: 0, actions: 0 };
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(h(SessionItem, {
+      sessionId: 's1',
+      title: 'hello world',
+      onClick: () => { calls.click += 1; },
+      onRename: () => {},
+      onDelete: () => {},
+      ...overrides,
+      ...(overrides.selectable ? { onToggleSelect: () => { calls.toggle += 1; } } : {}),
+    }), container);
+  });
+  return { el: container, calls };
+}
+
+const session: SessionItemData = { id: 's1', folder_id: 1, title: 'hello world' };
+
+async function mountMobile(overrides: Partial<MobileSessionRowProps> = {}) {
+  const calls = { select: 0, toggle: 0 };
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(h(MobileSessionRow, {
+      session,
+      isActive: false,
+      timeAgo: null,
+      onSelect: () => { calls.select += 1; },
+      onArchive: () => {},
+      onDelete: () => {},
+      onRename: () => {},
+      ...overrides,
+      ...(overrides.selectable ? { onToggleSelect: () => { calls.toggle += 1; } } : {}),
+    }), container);
+  });
+  return { el: container, calls };
+}
+
+function checkbox(el: HTMLElement): HTMLInputElement | null {
+  return el.querySelector('input[type="checkbox"]') as HTMLInputElement | null;
+}
+
+describe('desktop row batch mode', () => {
+  test('no checkbox while the sidebar is not selecting', async () => {
+    const { el } = await mountDesktop();
+    expect(checkbox(el)).toBeNull();
+    expect(el.querySelector('[data-selected]')).toBeNull();
+  });
+
+  test('draws a checkbox named after the row', async () => {
+    const { el } = await mountDesktop({ selectable: true });
+    expect(checkbox(el)?.getAttribute('aria-label')).toBe('Select hello world');
+  });
+
+  test('a click toggles the selection instead of opening the session', async () => {
+    const { el, calls } = await mountDesktop({ selectable: true });
+    const row = el.querySelector('[data-testid="session-item"]') as HTMLElement;
+    await act(async () => { row.click(); });
+    expect(calls.toggle).toBe(1);
+    expect(calls.click).toBe(0);
+  });
+
+  test('the checkbox click does not also fire the row', async () => {
+    const { el, calls } = await mountDesktop({ selectable: true });
+    await act(async () => { checkbox(el)?.click(); });
+    expect(calls.toggle).toBe(1);
+    expect(calls.click).toBe(0);
+  });
+
+  test('marks the selected row for styling and hides its actions', async () => {
+    const { el } = await mountDesktop({ selectable: true, selected: true });
+    const row = el.querySelector('[data-testid="session-item"]') as HTMLElement;
+    expect(row.getAttribute('data-selected')).toBe('true');
+    expect(checkbox(el)?.checked).toBe(true);
+    expect(el.querySelector('button[aria-label="Session actions"]')).toBeNull();
+  });
+
+  test('the normal row still opens the session and keeps its actions', async () => {
+    const { el, calls } = await mountDesktop();
+    const row = el.querySelector('[data-testid="session-item"]') as HTMLElement;
+    await act(async () => { row.click(); });
+    expect(calls.click).toBe(1);
+    expect(el.querySelector('button[aria-label="Session actions"]')).not.toBeNull();
+  });
+});
+
+describe('mobile row batch mode', () => {
+  test('no checkbox while the drawer is not selecting', async () => {
+    const { el } = await mountMobile();
+    expect(checkbox(el)).toBeNull();
+  });
+
+  test('a tap toggles the selection instead of opening the session', async () => {
+    const { el, calls } = await mountMobile({ selectable: true });
+    const row = el.querySelector('[data-testid="session-item"]') as HTMLElement;
+    await act(async () => { row.querySelector('button')?.click(); });
+    expect(calls.toggle).toBe(1);
+    expect(calls.select).toBe(0);
+  });
+
+  test('hides the row actions and the roster toggle in select mode', async () => {
+    const { el } = await mountMobile({ selectable: true, hasSubagents: true, onToggleExpand: () => {} });
+    expect(el.querySelector('button[aria-label="Session actions"]')).toBeNull();
+    expect(el.querySelector('button[aria-label*="subagents"]')).toBeNull();
+    expect(checkbox(el)?.getAttribute('aria-label')).toBe('Select hello world');
+  });
+});

package/src/client/components/layout/session-sidebar/SessionItem.tsx

@@ -3,6 +3,7 @@ import { Check, ChevronDown, ChevronRight, CircleQuestionMark, Loader2, MoreHori
 import { useInlineRename } from '@/client/hooks/ui/inline-rename';
 import { useSessionRenaming } from '@/client/hooks/workspace/renaming-sessions';
 import { SessionActionsMenu, useRowMenu } from '@/client/components/common/session-actions-menu';
+import { SelectionCheckbox } from '@/client/components/common/batch-selection/SelectionCheckbox';
 
 export interface SessionItemProps {
   /** The session this row draws; the key its in-flight rename is tracked under. */
@@ -29,6 +30,11 @@ export interface SessionItemProps {
   isExpanded?: boolean;
   hasSubagents?: boolean;
   onToggleExpand?: (e: TargetedMouseEvent<HTMLElement>) => void;
+  /** Draw a checkbox and let the row's click toggle the selection instead of
+   *  opening the session (batch mode). */
+  selectable?: boolean;
+  selected?: boolean;
+  onToggleSelect?: () => void;
 }
 
 export function SessionItem({
@@ -48,6 +54,9 @@ export function SessionItem({
   isExpanded = false,
   hasSubagents = false,
   onToggleExpand,
+  selectable = false,
+  selected = false,
+  onToggleSelect,
 }: SessionItemProps) {
   // A rename in flight is drawn in the same 16px slot the run spinner uses, so
   // a row the user just acted on says so where they are already looking. It
@@ -82,14 +91,32 @@ export function SessionItem({
       <div
         data-testid="session-item"
         data-session-id={String(sessionId)}
-        onClick={isEditing ? undefined : onClick}
-        onContextMenu={hasActions && !isEditing ? menu.openAtCursor : undefined}
+        data-selected={selectable && selected ? 'true' : undefined}
+        onClick={isEditing ? undefined : selectable ? onToggleSelect : onClick}
+        onContextMenu={hasActions && !isEditing && !selectable ? menu.openAtCursor : undefined}
         className={`group/item relative flex items-center w-full rounded-lg px-2 py-1.5 cursor-pointer text-xs transition-colors select-none ${
-          isActive
-            ? 'bg-ink/10 font-medium text-ink'
-            : 'text-ink/75 hover:text-ink hover:bg-ink/5'
+          selectable && selected
+            ? 'bg-ink/10 text-ink ring-1 ring-inset ring-ink/20'
+            : isActive
+              ? 'bg-ink/10 font-medium text-ink'
+              : 'text-ink/75 hover:text-ink hover:bg-ink/5'
         }`}
       >
+        {/* The checkbox takes the row's leading slot in batch mode. It replaces
+            the status/chevron column rather than sitting beside it: a row in
+            this mode is a choice, and a run spinner next to a checkbox reads as
+            a second, unrelated control. */}
+        {selectable ? (
+          <>
+            <SelectionCheckbox
+              checked={selected}
+              label={`Select ${title}`}
+              onChange={() => onToggleSelect?.()}
+            />
+            <span className="w-2 shrink-0" />
+          </>
+        ) : (
+          <>
         {/* One 16px slot owns both icons — never two side by side. A live run
             signal (blocked question, run spinner) holds the slot; otherwise the
             chevron is pinned, collapsed or expanded. While the signal holds it,
@@ -147,6 +174,8 @@ export function SessionItem({
 
         {/* Gap between icon and text */}
         <span className="w-2 shrink-0" />
+          </>
+        )}
 
         {/* Session Title - aligned straight with Folder Name */}
         {isEditing ? (
@@ -181,7 +210,7 @@ export function SessionItem({
             `ml-1` on top of the button's own `p-1` is the same 8px the title
             keeps from the time column, so the row's two gaps read as one
             rhythm instead of the glyph crowding the age. */}
-        {!isEditing && hasActions && (
+        {!isEditing && hasActions && !selectable && (
           <button
             type="button"
             onClick={menu.openBelow}

package/src/client/components/layout/session-sidebar/SessionList.tsx

@@ -1,7 +1,9 @@
 import { Category } from '@/client/components/layout/session-sidebar/CategoryItem';
+import type { BatchBinding } from '@/client/components/common/batch-selection/types';
+import type { WorkspaceFolderData } from '@/shared/types';
 
 interface SessionSidebarSessionListProps {
-  folders: any[];
+  folders: WorkspaceFolderData[];
   activeSessionId: number | string | null;
   searchQuery: string;
   showArchived: boolean;
@@ -10,6 +12,9 @@ interface SessionSidebarSessionListProps {
   onNewSessionForFolder: (id: number) => void;
   /** Surfaces a refused folder action (the reveal endpoint's own reason). */
   onToast?: (message: string, type?: 'success' | 'error') => void;
+  /** Present only while a batch selection is active. */
+  batch?: BatchBinding;
+  onStartSessionSelection?: (folderId: number) => void;
 }
 
 export function SessionSidebarSessionList({
@@ -21,6 +26,8 @@ export function SessionSidebarSessionList({
   onSelectSession,
   onNewSessionForFolder,
   onToast,
+  batch,
+  onStartSessionSelection,
 }: SessionSidebarSessionListProps) {
   // No fade wiring here: the app-wide scrollbar rule reveals this list's bar
   // from the document's own capture-phase listener (`lib/scrollbar-activity`),
@@ -43,6 +50,8 @@ export function SessionSidebarSessionList({
             showArchived={showArchived}
             sessionStatus={sessionStatus}
             onToast={onToast}
+            batch={batch}
+            onStartSessionSelection={onStartSessionSelection}
           />
         ))
       )}

package/src/client/components/layout/session-sidebar/Toolbar.test.ts

@@ -75,6 +75,8 @@ async function mount() {
       scheduledCount: 0,
       onRefresh: () => {},
       refreshing: false,
+      onSelectWorkspaces: () => {},
+      selecting: false,
     }), container);
   });
   return { el: container, calls };

package/src/client/components/layout/session-sidebar/Toolbar.tsx

@@ -1,9 +1,9 @@
-import { Archive, ArrowUpDown, Calendar, FolderPlus, Plus, RefreshCw, Search, X } from 'lucide-preact';
-import { useLayoutEffect, useRef, useState } from 'preact/hooks';
+import { Archive, ArrowUpDown, Calendar, FolderPlus, ListChecks, Plus, RefreshCw, Search, X } from 'lucide-preact';
 import type { SessionSortOption } from '@/shared/types';
 import { SortMenu } from '@/client/components/common/sort-menu';
 import { ToolbarOverflowMenu } from '@/client/components/layout/session-sidebar/OverflowMenu';
 import type { OverflowAction } from '@/client/components/layout/session-sidebar/OverflowMenu';
+import { useToolbarRowWidth } from '@/client/hooks/workspace/toolbar-row-width';
 import {
   SIDEBAR_TOOLBAR_PRIORITY,
   TOOLBAR_ROW_PADDING_PX,
@@ -32,37 +32,10 @@ interface SessionSidebarToolbarProps {
   onRefresh: () => void;
   /** True while the user-initiated refresh is in flight — spins the icon. */
   refreshing: boolean;
-}
-
-/**
- * The row's content width, kept current as the sidebar is dragged.
- *
- * The capacity decision needs the width the row actually has, and the sidebar
- * is resizable — a `ResizeObserver` is what makes the set of visible controls
- * follow a drag instead of being decided once at mount.
- */
-function useRowWidth() {
-  const ref = useRef<HTMLDivElement>(null);
-  const [width, setWidth] = useState(0);
-  // A layout effect, so the first measure lands BEFORE paint: with a passive
-  // effect the row drew every control and then dropped the ones that did not
-  // fit on the next frame.
-  useLayoutEffect(() => {
-    const element = ref.current;
-    if (!element) return;
-    // `clientWidth` includes the row's own `px-1`, and the capacity budget is
-    // a CONTENT width — leaving the padding in made the row 8px optimistic,
-    // which is exactly the margin an extra icon needs.
-    const measure = () => setWidth(Math.max(0, element.clientWidth - TOOLBAR_ROW_PADDING_PX));
-    measure();
-    if (typeof ResizeObserver === 'undefined') return;
-    // The sidebar is resizable, so the visible set has to follow a drag
-    // instead of being decided once at mount.
-    const observer = new ResizeObserver(measure);
-    observer.observe(element);
-    return () => observer.disconnect();
-  }, []);
-  return { ref, width };
+  /** Enter the workspace batch-selection mode (checkbox on each workspace). */
+  onSelectWorkspaces: () => void;
+  /** True while a batch selection is active — the control reads pressed. */
+  selecting: boolean;
 }
 
 const ICON_CLASS = 'shrink-0 w-7 h-7 inline-flex items-center justify-center rounded border transition-colors cursor-pointer';
@@ -88,8 +61,10 @@ export function SessionSidebarToolbar({
   scheduledCount,
   onRefresh,
   refreshing,
+  onSelectWorkspaces,
+  selecting,
 }: SessionSidebarToolbarProps) {
-  const { ref: rowRef, width } = useRowWidth();
+  const { ref: rowRef, width } = useToolbarRowWidth(TOOLBAR_ROW_PADDING_PX);
   const capacity = sidebarToolbarCapacity(width);
   const visible = new Set(SIDEBAR_TOOLBAR_PRIORITY.slice(0, capacity));
   const hidden = SIDEBAR_TOOLBAR_PRIORITY.slice(capacity);
@@ -111,6 +86,15 @@ export function SessionSidebarToolbar({
   if (hidden.includes('archive')) {
     overflowActions.push({ id: 'archive', label: archiveLabel, icon: Archive, onSelect: onToggleArchived, active: showArchived });
   }
+  if (hidden.includes('select')) {
+    overflowActions.push({
+      id: 'select',
+      label: selecting ? 'Cancel selection' : 'Select workspaces',
+      icon: ListChecks,
+      onSelect: onSelectWorkspaces,
+      active: selecting,
+    });
+  }
   if (hidden.includes('scheduler')) {
     overflowActions.push({ id: 'scheduler', label: schedulerLabel, icon: Calendar, onSelect: onScheduler });
   }
@@ -199,6 +183,18 @@ export function SessionSidebarToolbar({
               <Search size={14} />
             </button>
           )}
+          {visible.has('select') && (
+            <button
+              type="button"
+              title={selecting ? 'Cancel selection' : 'Select workspaces'}
+              aria-label={selecting ? 'Cancel selection' : 'Select workspaces'}
+              aria-pressed={selecting}
+              onClick={onSelectWorkspaces}
+              className={`${ICON_CLASS} ${selecting ? ICON_ACTIVE : ICON_IDLE}`}
+            >
+              <ListChecks size={14} />
+            </button>
+          )}
           {visible.has('archive') && (
             <button
               type="button"

package/src/client/components/layout/session-sidebar/index.tsx

@@ -6,6 +6,7 @@ import { UpdatePopup } from '@/client/components/layout/update-popup';
 import { SessionSidebarHeader } from '@/client/components/layout/session-sidebar/Header';
 import { SessionSidebarToolbar } from '@/client/components/layout/session-sidebar/Toolbar';
 import { SessionSidebarFooter } from '@/client/components/layout/session-sidebar/Footer';
+import { useAndroidDownload } from '@/client/hooks/ui/updates/android-download';
 import { SessionSidebarSessionList } from '@/client/components/layout/session-sidebar/SessionList';
 import { SessionListSkeleton } from '@/client/components/layout/session-sidebar/Skeleton';
 import { ToastStack } from '@/client/components/common/ToastStack';
@@ -18,6 +19,12 @@ import { useSessionSidebarController } from '@/client/hooks/chat/omp/session-sid
 import { startPendingSession } from '@/client/hooks/chat/omp/pending-sessions';
 import { useScheduledTaskCount } from '@/client/hooks/workspace/scheduled-tasks';
 import { cloneWorkspaceFolder, createWorkspaceFolder } from '@/client/hooks/workspace/new-workspace';
+import { useBatchSelection } from '@/client/hooks/workspace/batch-selection';
+import { useBatchDeleteRun } from '@/client/hooks/workspace/batch-delete-run';
+import { BatchActionBar } from '@/client/components/common/batch-selection/BatchActionBar';
+import { BatchDeleteModal } from '@/client/components/common/batch-selection/BatchDeleteModal';
+import type { BatchBinding } from '@/client/components/common/batch-selection/types';
+import { liveSelection, selectableSessionIds } from '@/shared/lib/workspace/batch-select';
 import type { AgentStreamStatus } from '@/shared/lib/chat/omp/status';
 
 export function SessionSidebar({ className = '', onClose, appSettings = {}, streamStatus }: { className?: string, onClose?: () => void, appSettings?: Record<string, any>, streamStatus?: AgentStreamStatus }) {
@@ -50,11 +57,51 @@ export function SessionSidebar({ className = '', onClose, appSettings = {}, stre
   const [schedulerOpen, setSchedulerOpen] = useState(false);
   const scheduledCount = useScheduledTaskCount();
   const updates = useUpdates();
+  // The Android download offer: null in a browser and null when this APK is
+  // already the newest published one, so the footer draws nothing.
+  const androidDownload = useAndroidDownload(window.__OMP_BOOTSTRAP__?.shellVersion);
   const { toasts, pushToast, dismissToast } = useToasts();
 
   // Sidebar inline states
   const [isSearchVisible, setIsSearchVisible] = useState(false);
 
+  // Batch selection: two separate modes (sessions from a workspace's `⋯` menu,
+  // workspaces from the toolbar). `batchDelete.pending` holds the ids the
+  // confirmation dialog is about; the bar's Delete opens it and never deletes
+  // on its own.
+  const batch = useBatchSelection();
+  const batchDelete = useBatchDeleteRun(refreshNow);
+
+  const scopeFolder = batch.scopeFolderId === null
+    ? null
+    : processedFolders.find((folder) => folder.id === batch.scopeFolderId) ?? null;
+  const batchAvailable = batch.mode === 'workspace'
+    ? processedFolders.map((folder) => String(folder.id))
+    : batch.mode === 'session'
+      ? selectableSessionIds(scopeFolder?.sessions ?? [], showArchived)
+      : [];
+  // The count and the payload are the LIVE selection: an id that vanished from
+  // the list (deleted in another tab, filtered away) is not something this bar
+  // may still claim, and not something Delete may still send.
+  const batchSelected = liveSelection(batch.selected, batchAvailable);
+
+  const batchBinding: BatchBinding | undefined = batch.mode
+    ? {
+        mode: batch.mode,
+        scopeFolderId: batch.scopeFolderId,
+        selected: batch.selected,
+        toggle: batch.toggle,
+        selectAllOf: batch.selectAllOf,
+        unselectAllOf: batch.unselectAllOf,
+        summaryOf: batch.summaryOf,
+      }
+    : undefined;
+
+  const startWorkspaceSelection = () => {
+    if (batch.mode === 'workspace') batch.end();
+    else batch.begin('workspace');
+  };
+
   // The popup's "Update now" hands the run over instead of starting its own: the
   // About modal is where an update has always been driven from and it owns the
   // live output, so this opens it and starts the run it will draw. The popup
@@ -131,6 +178,8 @@ export function SessionSidebar({ className = '', onClose, appSettings = {}, stre
           scheduledCount={scheduledCount}
           onRefresh={refreshNow}
           refreshing={isRefreshing}
+          onSelectWorkspaces={startWorkspaceSelection}
+          selecting={batch.mode !== null}
         />
 
         {initializing ? (
@@ -145,12 +194,29 @@ export function SessionSidebar({ className = '', onClose, appSettings = {}, stre
             onSelectSession={handleSelectSession}
             onNewSessionForFolder={handleNewSessionForFolder}
             onToast={pushToast}
+            batch={batchBinding}
+            onStartSessionSelection={(folderId) => batch.begin('session', folderId)}
+          />
+        )}
+
+        {batch.mode && (
+          <BatchActionBar
+            mode={batch.mode}
+            count={batchSelected.length}
+            total={batchAvailable.length}
+            busy={batchDelete.isDeleting}
+            scopeLabel={scopeFolder?.name}
+            onSelectAll={() => batch.selectAllOf(batchAvailable)}
+            onUnselectAll={() => batch.unselectAllOf(batchAvailable)}
+            onDelete={() => batchDelete.request(batchSelected)}
+            onCancel={batch.end}
           />
         )}
 
         <SessionSidebarFooter
           onSettings={() => setSettingsOpen(true)}
           onInfo={() => setInfoOpen(true)}
+          androidDownload={androidDownload}
           updateAvailable={updates.hasUpdate}
           onUpdateClick={() => {
             setInfoOpen(true);
@@ -174,6 +240,32 @@ export function SessionSidebar({ className = '', onClose, appSettings = {}, stre
           Its "Update now" hands the run to the About modal below. */}
       <UpdatePopup updates={updates} />
 
+      {/* Batch delete confirmation. It stays open on a refusal so the reasons
+          can be read; a fully successful run closes itself and leaves the mode. */}
+      <BatchDeleteModal
+        mode={batch.mode ?? 'session'}
+        count={batchDelete.pending.length}
+        scopeLabel={scopeFolder?.name}
+        isDeleting={batchDelete.isDeleting}
+        outcome={batchDelete.outcome}
+        onClose={() => {
+          // A run that finished cleanly also ends the mode; one that refused
+          // ids keeps it, so the rows that survived are still selected for a
+          // second attempt.
+          const refusedCount = batchDelete.outcome?.refused.length ?? 0;
+          batchDelete.cancel();
+          if (batchDelete.outcome && refusedCount === 0) batch.end();
+        }}
+        onConfirm={() => {
+          const mode = batch.mode ?? 'session';
+          void batchDelete.confirm(mode).then((result) => {
+            // A finished run leaves the mode; a refused one keeps it so the
+            // remaining rows are still selectable for a second attempt.
+            if (result && result.refused.length === 0) batch.end();
+          });
+        }}
+      />
+
       {/* New Workspace Modal */}
       <NewWorkspaceModal
         isOpen={newWorkspaceOpen}

package/src/client/components/mobile/LayoutWrapper.tsx

@@ -1,6 +1,7 @@
-import { useCallback, useState } from 'preact/hooks';
+import { useCallback, useEffect, useState } from 'preact/hooks';
 import { useSearchParams } from '@/client/lib/router/search-params';
 import { useKabmoEvent } from '@/client/hooks/ui/window-event';
+import { registerBackHandler } from '@/client/lib/native/back';
 import type { SettingsCategoryId } from '@/shared/types';
 import { MobileMainView } from '@/client/components/mobile/MainView';
 import { MobileSessionSidebar } from '@/client/components/mobile/SessionSidebar';
@@ -64,6 +65,36 @@ export function MobileLayoutWrapper({ onDesktopToggle, appSettings = {} }: Mobil
   );
   const mobileEditorMissing = mobileEditorMissingIds.size > 0;
 
+  // The Android shell's back button asks this layout first.
+  //
+  // Order is what the user sees, innermost first: the full-screen editor and
+  // diff cover everything, then the settings modal, then the drawer screens,
+  // and only then does the shell walk WebView history. Without this, back
+  // reopened the previous session while leaving the drawer that opened it on
+  // screen — the screens live in React state, not in the URL.
+  useEffect(() => {
+    return registerBackHandler(() => {
+      if (mobileEditorFile) {
+        setMobileEditorFile(null);
+        return true;
+      }
+      if (mobileDiff) {
+        setMobileDiff(null);
+        return true;
+      }
+      if (settingsOpen) {
+        setSettingsOpen(false);
+        setAutoOpenAddProvider(false);
+        return true;
+      }
+      if (currentScreen !== 'main') {
+        setCurrentScreen('main');
+        return true;
+      }
+      return false;
+    });
+  }, [mobileEditorFile, mobileDiff, settingsOpen, currentScreen]);
+
   const { folder: sessionFolder } = activeProjectForSession(folders, sessionId);
   const contextFolder = sessionFolder ?? (folderId ? folders.find(f => String(f.id) === String(folderId)) ?? null : null);
   const activeProjectPath = contextFolder?.project_path ?? null;