From ac4e39edc58c8fe29aebdea49d76b1d699f7ae9a Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Sun, 23 Aug 2026 14:08:10 -0700
Subject: [PATCH 1/2] feat(ui): redesign compact touch settings

---
 packages/editor/components/AppHeader.tsx      |   5 +
 packages/review-editor/App.tsx                |   3 +
 .../components/ReviewHeaderMenu.tsx           |   3 +
 packages/ui/components/PlanHeaderMenu.tsx     |   3 +
 .../Settings.compactDisplay.test.tsx          |   6 +-
 .../ui/components/Settings.mobile.test.tsx    | 153 +++++++
 packages/ui/components/Settings.tsx           | 392 +++++++++++++++---
 packages/ui/theme.css                         |  49 +++
 8 files changed, 554 insertions(+), 60 deletions(-)
 create mode 100644 packages/ui/components/Settings.mobile.test.tsx

diff --git a/packages/editor/components/AppHeader.tsx b/packages/editor/components/AppHeader.tsx
index 7c3f95ef2..c18586e58 100644
--- a/packages/editor/components/AppHeader.tsx
+++ b/packages/editor/components/AppHeader.tsx
@@ -194,6 +194,8 @@ export const AppHeader = React.memo<AppHeaderProps>(({
   bearConfigured,
   octarineConfigured,
 }) => {
+  const settingsReturnFocusRef = React.useRef<HTMLButtonElement>(null);
+
   return (
     <header
       data-app-header="true"
@@ -456,10 +458,13 @@ export const AppHeader = React.memo<AppHeaderProps>(({
             onExternalClose={onCloseSettings}
             gitUser={gitUser}
             agentTerminalAvailable={agentTerminalAvailable}
+            isCompactTouchLayout={compactTouchLayout}
+            returnFocusRef={settingsReturnFocusRef}
           />
         </div>
 
         <PlanHeaderMenu
+          triggerRef={settingsReturnFocusRef}
           appVersion={appVersion}
           updateInfo={updateInfo}
           origin={origin}
diff --git a/packages/review-editor/App.tsx b/packages/review-editor/App.tsx
index d5a023d52..882fb4a3a 100644
--- a/packages/review-editor/App.tsx
+++ b/packages/review-editor/App.tsx
@@ -345,6 +345,7 @@ const ReviewApp: React.FC = () => {
   const [showExportModal, setShowExportModal] = useState(false);
   const [showWorktreeDialog, setShowWorktreeDialog] = useState(false);
   const [openSettingsMenu, setOpenSettingsMenu] = useState(false);
+  const settingsReturnFocusRef = useRef<HTMLButtonElement>(null);
   const [showNoAnnotationsDialog, setShowNoAnnotationsDialog] = useState(false);
   const [isLoading, setIsLoading] = useState(true);
   const diffStyle = useConfigValue('diffStyle');
@@ -4034,6 +4035,7 @@ const ReviewApp: React.FC = () => {
             <div className="w-px h-5 bg-border/50 mx-1 hidden lg:block" />
 
             <ReviewHeaderMenu
+              triggerRef={settingsReturnFocusRef}
               onOpenSettings={() => setOpenSettingsMenu(true)}
               onOpenReviewSetup={sectionsCapable ? () => { reviewSetupIsFirstRun.current = false; setShowReviewSetup(true); } : undefined}
               onOpenExport={() => setShowExportModal(true)}
@@ -4534,6 +4536,7 @@ const ReviewApp: React.FC = () => {
             // Display tab hides the Split/Unified control rather than writing
             // the desktop preference from a phone.
             isCompactTouchLayout={isCompactTouchLayout}
+            returnFocusRef={settingsReturnFocusRef}
           />
         </div>
 
diff --git a/packages/review-editor/components/ReviewHeaderMenu.tsx b/packages/review-editor/components/ReviewHeaderMenu.tsx
index 64899ab0a..5a3a9c19e 100644
--- a/packages/review-editor/components/ReviewHeaderMenu.tsx
+++ b/packages/review-editor/components/ReviewHeaderMenu.tsx
@@ -33,6 +33,7 @@ export interface CompactReviewAction {
 }
 
 interface ReviewHeaderMenuProps {
+  triggerRef?: React.Ref<HTMLButtonElement>;
   onOpenSettings: () => void;
   onOpenReviewSetup?: () => void;
   onOpenExport: () => void;
@@ -56,6 +57,7 @@ interface ReviewHeaderMenuProps {
 }
 
 export const ReviewHeaderMenu: React.FC<ReviewHeaderMenuProps> = ({
+  triggerRef,
   onOpenSettings,
   onOpenReviewSetup,
   onOpenExport,
@@ -90,6 +92,7 @@ export const ReviewHeaderMenu: React.FC<ReviewHeaderMenuProps> = ({
       }
       renderTrigger={({ isOpen, toggleMenu }) => (
         <button
+          ref={triggerRef}
           data-pn-touch-target
           data-pn-touch-target-icon
           onClick={() => {
diff --git a/packages/ui/components/PlanHeaderMenu.tsx b/packages/ui/components/PlanHeaderMenu.tsx
index d054cf1c4..8e30cb5e4 100644
--- a/packages/ui/components/PlanHeaderMenu.tsx
+++ b/packages/ui/components/PlanHeaderMenu.tsx
@@ -14,6 +14,7 @@ import type { UpdateInfo } from '../hooks/useUpdateCheck';
 import type { Origin } from '@plannotator/core/agents';
 
 interface PlanHeaderMenuProps {
+  triggerRef?: React.Ref<HTMLButtonElement>;
   appVersion: string;
   updateInfo?: UpdateInfo | null;
   origin?: Origin | null;
@@ -48,6 +49,7 @@ export interface CompactPlanAction {
 }
 
 export const PlanHeaderMenu: React.FC<PlanHeaderMenuProps> = ({
+  triggerRef,
   appVersion,
   updateInfo,
   origin,
@@ -88,6 +90,7 @@ export const PlanHeaderMenu: React.FC<PlanHeaderMenuProps> = ({
       }
       renderTrigger={({ isOpen, toggleMenu }) => (
         <button
+          ref={triggerRef}
           id={compactTouchLayout ? 'pn-compact-plan-options-trigger' : undefined}
           data-pn-touch-target={compactTouchLayout || undefined}
           data-pn-touch-target-icon={compactTouchLayout || undefined}
diff --git a/packages/ui/components/Settings.compactDisplay.test.tsx b/packages/ui/components/Settings.compactDisplay.test.tsx
index 612b30047..53905e7d2 100644
--- a/packages/ui/components/Settings.compactDisplay.test.tsx
+++ b/packages/ui/components/Settings.compactDisplay.test.tsx
@@ -30,8 +30,10 @@ async function openDisplayTab(isCompactTouchLayout: boolean): Promise<void> {
     );
   });
 
-  const displayTab = Array.from(document.querySelectorAll<HTMLButtonElement>('button'))
-    .find((button) => button.textContent?.trim() === 'Editor');
+  const displayTab = isCompactTouchLayout
+    ? document.querySelector<HTMLButtonElement>('[data-pn-settings-section="display"]')
+    : Array.from(document.querySelectorAll<HTMLButtonElement>('button'))
+      .find((button) => button.textContent?.trim() === 'Editor');
   if (!displayTab) throw new Error('review display tab did not render');
   await act(async () => displayTab.click());
 }
diff --git a/packages/ui/components/Settings.mobile.test.tsx b/packages/ui/components/Settings.mobile.test.tsx
new file mode 100644
index 000000000..fee286dd1
--- /dev/null
+++ b/packages/ui/components/Settings.mobile.test.tsx
@@ -0,0 +1,153 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { Settings } from './Settings';
+
+const hasDom = typeof document !== 'undefined';
+let host: HTMLDivElement | null = null;
+let root: Root | null = null;
+
+const expectedSections = {
+  plan: ['general', 'theme', 'display', 'saving', 'labels', 'vim', 'shortcuts', 'hooks', 'files', 'obsidian', 'bear', 'octarine'],
+  review: ['general', 'theme', 'git', 'display', 'analysis', 'comments', 'ai', 'shortcuts', 'files'],
+  annotate: ['general', 'theme', 'vim', 'shortcuts', 'files'],
+} as const;
+
+async function nextFrame(): Promise<void> {
+  await act(async () => {
+    await new Promise<void>((resolve) => window.requestAnimationFrame(() => resolve()));
+  });
+}
+
+async function mountSettings(
+  mode: 'plan' | 'review' | 'annotate',
+  options: {
+    compact?: boolean;
+    returnFocusRef?: React.RefObject<HTMLButtonElement | null>;
+  } = {},
+): Promise<void> {
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  root = createRoot(host);
+  await act(async () => {
+    root?.render(
+      <Settings
+        taterMode={false}
+        onTaterModeChange={() => {}}
+        mode={mode}
+        externalOpen
+        isCompactTouchLayout={options.compact ?? true}
+        returnFocusRef={options.returnFocusRef}
+        aiProviders={mode === 'review'
+          ? [{ id: 'test', name: 'Test provider', capabilities: {} }]
+          : []
+        }
+      />,
+    );
+  });
+  await nextFrame();
+}
+
+function requireElement<T extends Element>(selector: string): T {
+  const element = document.querySelector<T>(selector);
+  if (!element) throw new Error(`Expected element: ${selector}`);
+  return element;
+}
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = null;
+  host?.remove();
+  host = null;
+  if (hasDom) {
+    document.body.replaceChildren();
+    window.localStorage.clear();
+  }
+});
+
+describe.if(hasDom)('compact touch Settings', () => {
+  for (const mode of ['plan', 'review', 'annotate'] as const) {
+    test(`${mode} exposes every section through the mobile information architecture`, async () => {
+      await mountSettings(mode);
+
+      const dialog = requireElement<HTMLElement>('[data-pn-settings-layout="compact"]');
+      expect(dialog.getAttribute('data-pn-settings-screen')).toBe('sections');
+      expect(dialog.closest('.pn-visible-viewport-stage')).not.toBeNull();
+      expect(document.querySelectorAll('[data-pn-settings-scroll-owner]')).toHaveLength(1);
+
+      const sectionIds = Array.from(
+        document.querySelectorAll<HTMLElement>('[data-pn-settings-section]'),
+        (element) => element.dataset.pnSettingsSection,
+      );
+      expect(sectionIds).toEqual([...expectedSections[mode]]);
+
+      for (const sectionId of expectedSections[mode]) {
+        const section = requireElement<HTMLButtonElement>(`[data-pn-settings-section="${sectionId}"]`);
+        await act(async () => section.click());
+        await nextFrame();
+
+        expect(dialog.getAttribute('data-pn-settings-screen')).toBe('detail');
+        expect(requireElement('[data-pn-settings-section-content]').getAttribute('data-pn-settings-section-content')).toBe(sectionId);
+        expect(document.querySelector('[aria-label="Close settings"]')).toBeNull();
+
+        const back = requireElement<HTMLButtonElement>('[aria-label="Back to Settings"]');
+        await act(async () => back.click());
+        await nextFrame();
+        expect(dialog.getAttribute('data-pn-settings-screen')).toBe('sections');
+        const activeElement = document.activeElement;
+        expect(activeElement instanceof HTMLElement ? activeElement.dataset.pnSettingsSection : undefined).toBe(sectionId);
+      }
+    });
+  }
+
+  test('focus starts on Close, stays contained, Escape closes, and focus returns', async () => {
+    const returnButton = document.createElement('button');
+    returnButton.textContent = 'Options';
+    document.body.appendChild(returnButton);
+    returnButton.focus();
+    const returnFocusRef = { current: returnButton };
+
+    await mountSettings('plan', { returnFocusRef });
+
+    const close = requireElement<HTMLButtonElement>('[aria-label="Close settings"]');
+    expect(document.activeElement).toBe(close);
+    expect(document.activeElement?.tagName).not.toBe('INPUT');
+
+    const lastSection = requireElement<HTMLButtonElement>('[data-pn-settings-section="octarine"]');
+    lastSection.focus();
+    await act(async () => {
+      lastSection.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', bubbles: true }));
+    });
+    expect(document.activeElement).toBe(close);
+
+    await act(async () => {
+      close.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    });
+    await nextFrame();
+    expect(document.querySelector('[role="dialog"]')).toBeNull();
+    expect(document.activeElement).toBe(returnButton);
+  });
+});
+
+describe.if(hasDom)('desktop Settings control', () => {
+  test('keeps the existing centered desktop dialog and tab composition', async () => {
+    await mountSettings('plan', { compact: false });
+
+    const dialog = requireElement<HTMLElement>('[data-pn-settings-layout="desktop"]');
+    expect(dialog.classList.contains('max-w-2xl')).toBe(true);
+    expect(dialog.classList.contains('max-h-[85vh]')).toBe(true);
+    expect(document.querySelector('[data-pn-settings-section]')).toBeNull();
+    expect(document.querySelector('.pn-visible-viewport-stage')).toBeNull();
+    expect(document.body.textContent).toContain('Your Identity');
+  });
+});
+
+test('compact CSS enforces touch targets, 16px editing controls, and reduced motion', async () => {
+  const css = await Bun.file(new URL('../theme.css', import.meta.url)).text();
+  expect(css).toContain("[data-pn-settings-layout='compact'] button:not([role='switch'])");
+  expect(css).toContain('min-block-size: var(--pn-touch-target)');
+  expect(css).toContain("[data-pn-settings-layout='compact'] [role='switch']::before");
+  expect(css).toContain('font-size: 1rem !important');
+  expect(css).toContain('@media (prefers-reduced-motion: reduce)');
+  expect(css).toContain('transition-duration: 0.01ms !important');
+});
diff --git a/packages/ui/components/Settings.tsx b/packages/ui/components/Settings.tsx
index 4a0e133cc..427cc9892 100644
--- a/packages/ui/components/Settings.tsx
+++ b/packages/ui/components/Settings.tsx
@@ -74,10 +74,30 @@ import {
   type FileBrowserSettings,
 } from '../utils/fileBrowser';
 import { requestVimDocumentFocus } from '../hooks/useVimDocumentFocus';
+import { useViewportEnvironment } from '../hooks/useViewportEnvironment';
 import { AnalysisLayerToggle } from './AnalysisLayerToggle';
 
 type SettingsTab = 'general' | 'theme' | 'git' | 'display' | 'analysis' | 'saving' | 'labels' | 'vim' | 'shortcuts' | 'ai' | 'files' | 'obsidian' | 'bear' | 'octarine' | 'comments' | 'hooks';
 
+const SETTINGS_TAB_DESCRIPTIONS: Record<SettingsTab, string> = {
+  general: 'Identity and session behavior',
+  theme: 'Appearance, color, and favicon',
+  git: 'Review start view and change scope',
+  display: 'Layout and presentation preferences',
+  analysis: 'Semantic changes and call flow',
+  saving: 'Plan history and quick-save defaults',
+  labels: 'Quick feedback presets',
+  vim: 'Document navigation and HUD',
+  shortcuts: 'Keyboard reference',
+  ai: 'Provider and model defaults',
+  files: 'Extra file browser directories',
+  obsidian: 'Vault saving and browsing',
+  bear: 'Bear Notes export preferences',
+  octarine: 'Workspace export preferences',
+  comments: 'Conventional review labels',
+  hooks: 'Plan and review automation',
+};
+
 interface SettingsProps {
   taterMode: boolean;
   onTaterModeChange: (enabled: boolean) => void;
@@ -96,10 +116,12 @@ interface SettingsProps {
    *  (base ref unresolvable) — the Git tab shows a note that the Git-status
    *  preference can't take effect in THIS repo. */
   sinceBaseUnavailable?: boolean;
-  /** The host is rendering its compact touch shell (review only). Display
-   *  settings that the compact shell overrides for the session are hidden
-   *  there instead of silently editing the desktop preference. */
+  /** The host is rendering its compact touch shell. Settings becomes a
+   *  full-screen, touch-native surface; review display preferences that the
+   *  compact shell overrides for the session remain protected. */
   isCompactTouchLayout?: boolean;
+  /** Focus target restored after an externally opened Settings surface closes. */
+  returnFocusRef?: React.RefObject<HTMLButtonElement | null>;
   /** Override Obsidian vault detection (default = GET /api/obsidian/vaults). */
   onDetectObsidianVaults?: () => Promise<string[]>;
   /** This annotate session actually offers the Agent TUI, so its Position
@@ -848,24 +870,73 @@ const CommentsTab: React.FC = () => {
   );
 };
 
-export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, sinceBaseUnavailable, isCompactTouchLayout = false, onDetectObsidianVaults, agentTerminalAvailable = false }) => {
+export const Settings: React.FC<SettingsProps> = ({
+  taterMode,
+  onTaterModeChange,
+  onIdentityChange,
+  origin,
+  mode = 'plan',
+  onUIPreferencesChange,
+  externalOpen,
+  onExternalClose,
+  aiProviders = [],
+  gitUser,
+  sinceBaseUnavailable,
+  isCompactTouchLayout = false,
+  returnFocusRef,
+  onDetectObsidianVaults,
+  agentTerminalAvailable = false,
+}) => {
+  useViewportEnvironment();
   const [showDialog, setShowDialog] = useState(false);
+  const [compactScreen, setCompactScreen] = useState<'sections' | 'detail'>('sections');
   const settingsWasOpenRef = useRef(false);
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const internalTriggerRef = useRef<HTMLButtonElement>(null);
+  const closeButtonRef = useRef<HTMLButtonElement>(null);
+  const backButtonRef = useRef<HTMLButtonElement>(null);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+  const compactSectionReturnIdRef = useRef<SettingsTab | null>(null);
   const [themePreview, setThemePreview] = useState(false);
 
   useEffect(() => {
     const wasOpen = settingsWasOpenRef.current;
     settingsWasOpenRef.current = showDialog;
-    if (
-      wasOpen
-      && !showDialog
-      && !themePreview
-      && mode !== 'review'
-      && configStore.get('vimModeEnabled')
-    ) {
-      requestVimDocumentFocus();
+
+    let animationFrame: number | null = null;
+    if (!wasOpen && showDialog) {
+      const activeElement = document.activeElement;
+      previousFocusRef.current = returnFocusRef?.current
+        ?? (activeElement instanceof HTMLElement ? activeElement : null)
+        ?? internalTriggerRef.current;
+      animationFrame = window.requestAnimationFrame(() => {
+        const initialControl = isCompactTouchLayout && compactScreen === 'detail'
+          ? backButtonRef.current
+          : closeButtonRef.current;
+        initialControl?.focus({ preventScroll: true });
+      });
     }
-  }, [mode, showDialog, themePreview]);
+
+    if (wasOpen && !showDialog && !themePreview) {
+      const explicitFocusTarget = returnFocusRef?.current;
+      if (explicitFocusTarget) {
+        animationFrame = window.requestAnimationFrame(() => {
+          if (explicitFocusTarget.isConnected) explicitFocusTarget.focus({ preventScroll: true });
+        });
+      } else if (mode !== 'review' && configStore.get('vimModeEnabled')) {
+        requestVimDocumentFocus();
+      } else {
+        const focusTarget = previousFocusRef.current;
+        animationFrame = window.requestAnimationFrame(() => {
+          if (focusTarget?.isConnected) focusTarget.focus({ preventScroll: true });
+        });
+      }
+    }
+
+    return () => {
+      if (animationFrame !== null) window.cancelAnimationFrame(animationFrame);
+    };
+  }, [compactScreen, isCompactTouchLayout, mode, returnFocusRef, showDialog, themePreview]);
 
   useEffect(() => {
     if (!themePreview) return;
@@ -954,6 +1025,7 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
   // Sync external open state
   useEffect(() => {
     if (externalOpen) {
+      setCompactScreen('sections');
       setShowDialog(true);
       onExternalClose?.();
     }
@@ -1116,11 +1188,79 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
   // Default (Plannotator cookie identity) is editable, so this is true and the
   // controls render exactly as before.
   const identityEditable = isIdentityEditable();
+  const activeTabLabel = [...mainTabs, ...integrationTabs]
+    .find((tab) => tab.id === activeTab)?.label ?? 'Settings';
+
+  const closeSettings = () => {
+    setShowDialog(false);
+  };
+
+  const openCompactSection = (
+    tab: { id: SettingsTab; label: string },
+  ) => {
+    compactSectionReturnIdRef.current = tab.id;
+    setActiveTab(tab.id);
+    setCompactScreen('detail');
+    window.requestAnimationFrame(() => backButtonRef.current?.focus({ preventScroll: true }));
+  };
+
+  const showCompactSectionList = () => {
+    setCompactScreen('sections');
+    window.requestAnimationFrame(() => {
+      const sectionId = compactSectionReturnIdRef.current;
+      if (!sectionId) return;
+      dialogRef.current
+        ?.querySelector<HTMLButtonElement>(`[data-pn-settings-section="${sectionId}"]`)
+        ?.focus({ preventScroll: true });
+    });
+  };
+
+  const handleDialogKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === 'Escape' && !event.defaultPrevented) {
+      event.preventDefault();
+      event.stopPropagation();
+      closeSettings();
+      return;
+    }
+
+    if (event.key !== 'Tab' || event.defaultPrevented) return;
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    const focusable = Array.from(dialog.querySelectorAll<HTMLElement>(
+      'button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+    )).filter((element) => {
+      if (element.hidden || element.getAttribute('aria-hidden') === 'true') return false;
+      const style = window.getComputedStyle(element);
+      return style.display !== 'none' && style.visibility !== 'hidden';
+    });
+    const first = focusable.at(0);
+    const last = focusable.at(-1);
+    if (!first || !last) {
+      event.preventDefault();
+      return;
+    }
+
+    const activeElement = document.activeElement;
+    if (event.shiftKey && (activeElement === first || !dialog.contains(activeElement))) {
+      event.preventDefault();
+      last.focus({ preventScroll: true });
+    } else if (!event.shiftKey && (activeElement === last || !dialog.contains(activeElement))) {
+      event.preventDefault();
+      first.focus({ preventScroll: true });
+    }
+  };
 
   return (
     <>
       <button
-        onClick={() => setShowDialog(true)}
+        ref={internalTriggerRef}
+        type="button"
+        aria-label="Settings"
+        onClick={() => {
+          previousFocusRef.current = internalTriggerRef.current;
+          setCompactScreen('sections');
+          setShowDialog(true);
+        }}
         className="relative p-1.5 rounded-md text-muted-foreground hover:text-foreground hover:bg-muted transition-colors"
         title="Settings"
       >
@@ -1132,57 +1272,176 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
 
       {showDialog && !themePreview && createPortal(
         <div
-          className="fixed inset-0 z-[100] flex items-center justify-center bg-background/80 backdrop-blur-sm p-4"
-          onClick={() => setShowDialog(false)}
+          className={isCompactTouchLayout
+            ? 'pn-visible-viewport-stage z-[100] flex flex-col bg-card'
+            : 'fixed inset-0 z-[100] flex items-center justify-center bg-background/80 backdrop-blur-sm p-4'
+          }
+          onClick={isCompactTouchLayout ? undefined : closeSettings}
         >
           <div
-            className="bg-card border border-border rounded-xl w-full max-w-2xl max-h-[85vh] flex flex-col shadow-2xl relative overflow-hidden"
+            ref={dialogRef}
+            data-pn-settings-layout={isCompactTouchLayout ? 'compact' : 'desktop'}
+            data-pn-settings-screen={isCompactTouchLayout ? compactScreen : undefined}
+            className={isCompactTouchLayout
+              ? 'relative flex min-h-0 flex-1 flex-col overflow-hidden bg-card'
+              : 'bg-card border border-border rounded-xl w-full max-w-2xl max-h-[85vh] flex flex-col shadow-2xl relative overflow-hidden'
+            }
             role="dialog"
             aria-modal="true"
             aria-labelledby="plannotator-settings-title"
             onClick={e => e.stopPropagation()}
-            onKeyDown={(event) => {
-              if (event.key !== 'Escape' || event.defaultPrevented) return;
-              event.preventDefault();
-              event.stopPropagation();
-              setShowDialog(false);
-            }}
+            onKeyDown={handleDialogKeyDown}
           >
             {taterMode && <TaterSpritePullup />}
-            <div className="flex items-center justify-between p-4 border-b border-border">
-              <h3 id="plannotator-settings-title" className="font-semibold text-sm">Settings</h3>
-              <button
-                type="button"
-                aria-label="Close settings"
-                onClick={() => setShowDialog(false)}
-                className="p-1.5 rounded-md bg-muted hover:bg-muted/80 text-foreground transition-colors"
-              >
-                <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.5}>
-                  <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
-                </svg>
-              </button>
-            </div>
-
-            <div className="flex flex-col md:flex-row md:min-h-[420px] flex-1 min-h-0 overflow-hidden">
-              {/* Mobile: horizontal tab bar */}
-              <nav className="md:hidden flex overflow-x-auto border-b border-border px-2 py-1.5 gap-1 flex-shrink-0">
-                {[...mainTabs, ...integrationTabs].map(tab => (
+            {isCompactTouchLayout ? (
+              <div className="grid min-h-14 shrink-0 grid-cols-[2.75rem_minmax(0,1fr)_2.75rem] items-center border-b border-border/80 px-2">
+                {compactScreen === 'detail' ? (
+                  <button
+                    ref={backButtonRef}
+                    type="button"
+                    data-pn-touch-target
+                    data-pn-touch-target-icon
+                    aria-label="Back to Settings"
+                    onClick={showCompactSectionList}
+                    className="grid h-11 w-11 place-items-center rounded-lg text-foreground transition-colors active:bg-muted"
+                  >
+                    <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2} aria-hidden="true">
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M15 19l-7-7 7-7" />
+                    </svg>
+                  </button>
+                ) : (
+                  <span aria-hidden="true" />
+                )}
+                <h3
+                  id="plannotator-settings-title"
+                  className="min-w-0 truncate px-2 text-center text-base font-semibold tracking-tight"
+                >
+                  {compactScreen === 'detail' ? activeTabLabel : 'Settings'}
+                </h3>
+                {compactScreen === 'sections' ? (
                   <button
-                    key={tab.id}
-                    onClick={() => setActiveTab(tab.id)}
-                    className={`px-3 py-1.5 rounded text-xs whitespace-nowrap transition-colors flex items-center gap-1.5 ${
-                      activeTab === tab.id
-                        ? 'bg-primary/10 text-primary font-medium'
-                        : 'text-muted-foreground hover:text-foreground hover:bg-muted/50'
-                    }`}
+                    ref={closeButtonRef}
+                    type="button"
+                    data-pn-touch-target
+                    data-pn-touch-target-icon
+                    aria-label="Close settings"
+                    onClick={closeSettings}
+                    className="grid h-11 w-11 place-items-center rounded-lg text-foreground transition-colors active:bg-muted"
                   >
-                    {tab.label}
+                    <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.25} aria-hidden="true">
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                    </svg>
                   </button>
-                ))}
-              </nav>
+                ) : (
+                  <span aria-hidden="true" />
+                )}
+              </div>
+            ) : (
+              <div className="flex items-center justify-between p-4 border-b border-border">
+                <h3 id="plannotator-settings-title" className="font-semibold text-sm">Settings</h3>
+                <button
+                  ref={closeButtonRef}
+                  type="button"
+                  aria-label="Close settings"
+                  onClick={closeSettings}
+                  className="p-1.5 rounded-md bg-muted hover:bg-muted/80 text-foreground transition-colors"
+                >
+                  <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.5}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                  </svg>
+                </button>
+              </div>
+            )}
+
+            <div className={isCompactTouchLayout
+              ? 'flex flex-1 min-h-0 overflow-hidden'
+              : 'flex flex-col md:flex-row md:min-h-[420px] flex-1 min-h-0 overflow-hidden'
+            }>
+              {isCompactTouchLayout && compactScreen === 'sections' && (
+                <OverlayScrollArea
+                  data-pn-settings-scroll-owner
+                  className="min-h-0 flex-1 overscroll-contain"
+                >
+                  <nav aria-label="Settings sections" className="mx-auto w-full max-w-2xl px-3 py-4">
+                    <div className="px-2 pb-2 text-[11px] font-semibold uppercase tracking-[0.12em] text-muted-foreground">
+                      Preferences
+                    </div>
+                    <div className="overflow-hidden rounded-xl border border-border/80 bg-muted/15">
+                      {mainTabs.map((tab, index) => (
+                        <button
+                          key={tab.id}
+                          type="button"
+                          data-pn-settings-section={tab.id}
+                          onClick={() => openCompactSection(tab)}
+                          className={`flex w-full min-w-0 items-center gap-3 px-4 py-3 text-left transition-colors active:bg-muted ${index > 0 ? 'border-t border-border/70' : ''}`}
+                        >
+                          <span className="min-w-0 flex-1">
+                            <span className="block text-[0.9375rem] font-medium text-foreground">{tab.label}</span>
+                            <span className="mt-0.5 block text-[0.8125rem] leading-snug text-muted-foreground">
+                              {tab.id === 'display' && mode === 'review'
+                                ? 'Code font and diff presentation'
+                                : SETTINGS_TAB_DESCRIPTIONS[tab.id]}
+                            </span>
+                          </span>
+                          <svg className="h-4 w-4 shrink-0 text-muted-foreground/70" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2} aria-hidden="true">
+                            <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
+                          </svg>
+                        </button>
+                      ))}
+                    </div>
 
-              {/* Desktop: sidebar */}
-              <nav className="hidden md:block w-40 border-r border-border p-2 flex-shrink-0">
+                    {integrationTabs.length > 0 && (
+                      <>
+                        <div className="px-2 pb-2 pt-6 text-[11px] font-semibold uppercase tracking-[0.12em] text-muted-foreground">
+                          Integrations
+                        </div>
+                        <div className="overflow-hidden rounded-xl border border-border/80 bg-muted/15">
+                          {integrationTabs.map((tab, index) => (
+                            <button
+                              key={tab.id}
+                              type="button"
+                              data-pn-settings-section={tab.id}
+                              onClick={() => openCompactSection(tab)}
+                              className={`flex w-full min-w-0 items-center gap-3 px-4 py-3 text-left transition-colors active:bg-muted ${index > 0 ? 'border-t border-border/70' : ''}`}
+                            >
+                              <span className="min-w-0 flex-1">
+                                <span className="block text-[0.9375rem] font-medium text-foreground">{tab.label}</span>
+                                <span className="mt-0.5 block text-[0.8125rem] leading-snug text-muted-foreground">
+                                  {SETTINGS_TAB_DESCRIPTIONS[tab.id]}
+                                </span>
+                              </span>
+                              <svg className="h-4 w-4 shrink-0 text-muted-foreground/70" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2} aria-hidden="true">
+                                <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
+                              </svg>
+                            </button>
+                          ))}
+                        </div>
+                      </>
+                    )}
+                  </nav>
+                </OverlayScrollArea>
+              )}
+
+              {!isCompactTouchLayout && (
+                <>
+                  {/* Narrow fine-pointer desktop: preserve the incumbent horizontal tab bar. */}
+                  <nav className="md:hidden flex overflow-x-auto border-b border-border px-2 py-1.5 gap-1 flex-shrink-0">
+                    {[...mainTabs, ...integrationTabs].map(tab => (
+                      <button
+                        key={tab.id}
+                        onClick={() => setActiveTab(tab.id)}
+                        className={`px-3 py-1.5 rounded text-xs whitespace-nowrap transition-colors flex items-center gap-1.5 ${
+                          activeTab === tab.id
+                            ? 'bg-primary/10 text-primary font-medium'
+                            : 'text-muted-foreground hover:text-foreground hover:bg-muted/50'
+                        }`}
+                      >
+                        {tab.label}
+                      </button>
+                    ))}
+                  </nav>
+
+                  <nav className="hidden md:block w-40 border-r border-border p-2 flex-shrink-0">
                 <div className="space-y-0.5">
                   {mainTabs.map(tab => (
                     <button
@@ -1221,11 +1480,23 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
                     </div>
                   </>
                 )}
-              </nav>
+                  </nav>
+                </>
+              )}
 
               {/* Content — scrollable */}
-              <OverlayScrollArea className="flex-1 min-h-0">
-              <div className="p-4 space-y-4">
+              {(!isCompactTouchLayout || compactScreen === 'detail') && (
+              <OverlayScrollArea
+                data-pn-settings-scroll-owner={isCompactTouchLayout || undefined}
+                className="flex-1 min-h-0 overscroll-contain"
+              >
+              <div
+                data-pn-settings-section-content={activeTab}
+                className={isCompactTouchLayout
+                  ? 'mx-auto w-full max-w-2xl space-y-4 px-4 py-5 sm:px-6'
+                  : 'p-4 space-y-4'
+                }
+              >
 
                 {/* === GENERAL TAB === */}
                 {activeTab === 'general' && (
@@ -2135,7 +2406,7 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
                         <div className="border-t border-border" />
 
                         <div className="space-y-3">
-                          <div className="flex gap-3">
+                          <div className="pn-settings-obsidian-destination flex gap-3">
                             <div className="flex-1 space-y-1.5">
                               <label className="text-xs text-muted-foreground">Vault</label>
                               {vaultsLoading ? (
@@ -2472,6 +2743,7 @@ tags: [plan, ...]
 
               </div>
               </OverlayScrollArea>
+              )}
             </div>
           </div>
         </div>,
@@ -2479,7 +2751,10 @@ tags: [plan, ...]
       )}
 
       {themePreview && createPortal(
-        <div className="fixed inset-0 z-[100] flex flex-col pointer-events-none">
+        <div className={isCompactTouchLayout
+          ? 'pn-visible-viewport-stage z-[100] flex flex-col pointer-events-none'
+          : 'fixed inset-0 z-[100] flex flex-col pointer-events-none'
+        }>
           <div className="flex-1" />
           <div
             className="pointer-events-auto w-full bg-card border-t-2 border-primary/30 shadow-[0_-4px_20px_rgba(0,0,0,0.4)] flex flex-col max-h-[35vh] overflow-hidden"
@@ -2488,6 +2763,7 @@ tags: [plan, ...]
             <div className="flex items-center justify-between px-4 py-2.5 border-b border-border flex-shrink-0">
               <span className="text-xs font-medium text-muted-foreground">Theme Preview</span>
               <button
+                data-pn-touch-target={isCompactTouchLayout || undefined}
                 onClick={() => { setThemePreview(false); setShowDialog(true); }}
                 className="px-2.5 py-1 rounded-md text-xs font-medium bg-primary text-primary-foreground hover:bg-primary/90 transition-colors"
               >
diff --git a/packages/ui/theme.css b/packages/ui/theme.css
index 023f4974a..46d71ee63 100644
--- a/packages/ui/theme.css
+++ b/packages/ui/theme.css
@@ -817,6 +817,55 @@ body:has([data-pn-document-scroll="true"]) > #root {
   overscroll-behavior: contain;
 }
 
+/* Compact Settings is a portaled full-stage surface. Its section list or
+ * section detail is the only scroll owner, while the surrounding stage stays
+ * pinned to the observed visual viewport through keyboard and browser-chrome
+ * changes. Desktop Settings does not carry this marker. */
+[data-pn-settings-layout='compact'] {
+  min-inline-size: 0;
+  overflow-wrap: anywhere;
+}
+
+[data-pn-settings-layout='compact'] button:not([role='switch']) {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+[data-pn-settings-layout='compact'] [role='switch']::before {
+  position: absolute;
+  inset: -0.625rem -0.125rem;
+  content: '';
+}
+
+[data-pn-settings-layout='compact']
+  :is(input:not([type='range']):not([type='color']):not([type='checkbox']):not([type='radio']), select, textarea) {
+  min-block-size: var(--pn-touch-target);
+  font-size: 1rem !important;
+}
+
+[data-pn-settings-layout='compact'] input[type='range'] {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+[data-pn-settings-layout='compact'] .pn-settings-obsidian-destination {
+  flex-direction: column;
+}
+
+[data-pn-settings-layout='compact'] .pn-settings-obsidian-destination > * {
+  width: 100%;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-pn-settings-layout='compact'],
+  [data-pn-settings-layout='compact'] * {
+    scroll-behavior: auto !important;
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+
 /* The navigator reuses information-dense desktop browser content, but its
  * interactive rows become physical controls on touch. Scope both the 44px
  * target and the TOC's legible type lift to the compact stage only. */

From 6c3a48818e0803d989a071f64a49898f1a837593 Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Sun, 23 Aug 2026 14:11:30 -0700
Subject: [PATCH 2/2] chore(core): refresh guide viewer manifest

---
 packages/core/guide-viewer-manifest.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/core/guide-viewer-manifest.ts b/packages/core/guide-viewer-manifest.ts
index a3446bd79..4e99790be 100644
--- a/packages/core/guide-viewer-manifest.ts
+++ b/packages/core/guide-viewer-manifest.ts
@@ -6,9 +6,9 @@ import type { GuideViewerAssets } from "./guide-format";
 
 export const GUIDE_VIEWER_MANIFEST: Omit<GuideViewerAssets, "baseUrl"> = {
   js: "viewer.CTfggrYt.js",
-  css: "viewer.BdruF6Mj.css",
+  css: "viewer.bodgv3Hj.css",
   jsIntegrity: "sha384-It85Hkx0/d1Xme4SJjt3shHybLPGucRF/OODzE84mbOmGH8fK66eFNzgFRXe2W4Z",
-  cssIntegrity: "sha384-9i0z0HV8a5Hr0SAQt0+pUfQE96MTbGaCWtZlSzhk+HKIHXsqrGi16HQA4mlEWRvx",
+  cssIntegrity: "sha384-QdcBsIL0BoPsyZoTpe07CMpF0oKoBI3udITgij6RMlwBTW3Qp9SVR2na165Fit+H",
   langs: {
     "astro": "chunks/astro.BykyiR6i.js",
     "c": "chunks/c.BIGW1oBm.js",