From d040c32e50f99d634aadb31dff01b342ef32f59e Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Sun, 23 Aug 2026 14:17:52 -0700
Subject: [PATCH 1/2] fix: harden secondary inputs on mobile

---
 packages/editor/App.tsx                       |   2 +
 .../review-editor/components/AIConfigBar.tsx  |   6 +-
 packages/review-editor/components/AITab.tsx   |   1 +
 .../components/AnnotationToolbar.tsx          |   2 +
 .../review-editor/components/AskAIInput.tsx   |   1 +
 .../components/BaseBranchPicker.tsx           |   7 +-
 .../components/CallFlowSearchControls.tsx     |   7 +
 .../ExpandedCommentDialog.mobile.test.tsx     |   1 +
 .../components/ExpandedCommentDialog.tsx      |   1 +
 .../components/FileCommentBanner.tsx          |   1 +
 .../components/PRCommentsTab.tsx              |   1 +
 .../review-editor/components/PanelChrome.tsx  |   3 +
 .../SuggestionModal.mobile.test.tsx           |  83 +++++++
 .../components/SuggestionModal.tsx            | 208 ++++++++++--------
 .../review-editor/components/ToolbarHost.tsx  |  16 +-
 .../components/WorktreePicker.tsx             |   9 +-
 .../components/guide/GuideEmptyState.tsx      |   9 +-
 packages/ui/components/AgentControls.tsx      |   7 +-
 packages/ui/components/AgentsTab.tsx          |  30 ++-
 packages/ui/components/AttachmentsButton.tsx  |   1 +
 packages/ui/components/CodeFilePopout.tsx     |   5 +-
 packages/ui/components/ExportModal.tsx        |  22 +-
 .../ui/components/ImageAnnotator/index.tsx    |  15 +-
 .../ui/components/ImportModal.mobile.test.tsx | 131 +++++++++++
 packages/ui/components/ImportModal.tsx        |  45 ++--
 .../MarkdownEditor.extensions.test.tsx        |   2 +
 packages/ui/components/MarkdownEditor.tsx     |  12 +-
 packages/ui/components/PlanHeaderMenu.tsx     |   2 +-
 .../components/PopoutDialog.mobile.test.tsx   |  43 ++++
 packages/ui/components/PopoutDialog.tsx       |  44 ++--
 .../SearchableSelect.mobile.test.tsx          |  77 +++++++
 packages/ui/components/SearchableSelect.tsx   |   4 +-
 packages/ui/components/blocks/TablePopout.tsx |   1 +
 packages/ui/components/core/textarea.tsx      |   1 +
 .../goal-setup/GoalSetupSurface.tsx           |   1 +
 .../ui/components/sidebar/FileBrowser.tsx     |   1 +
 .../components/ui/mobile-foundation.test.tsx  |  16 ++
 packages/ui/components/ui/textarea.tsx        |   1 +
 .../ui/hooks/useModalFocusLifecycle.test.tsx  |  63 ++++++
 packages/ui/hooks/useModalFocusLifecycle.ts   |  56 +++++
 .../ui/hooks/useViewportEnvironment.test.tsx  |  21 ++
 packages/ui/hooks/useViewportEnvironment.ts   |   9 +-
 packages/ui/theme.css                         |  61 ++++-
 43 files changed, 866 insertions(+), 163 deletions(-)
 create mode 100644 packages/review-editor/components/SuggestionModal.mobile.test.tsx
 create mode 100644 packages/ui/components/ImportModal.mobile.test.tsx
 create mode 100644 packages/ui/components/PopoutDialog.mobile.test.tsx
 create mode 100644 packages/ui/components/SearchableSelect.mobile.test.tsx
 create mode 100644 packages/ui/hooks/useModalFocusLifecycle.test.tsx
 create mode 100644 packages/ui/hooks/useModalFocusLifecycle.ts

diff --git a/packages/editor/App.tsx b/packages/editor/App.tsx
index d7ec25258..a15fa17b1 100644
--- a/packages/editor/App.tsx
+++ b/packages/editor/App.tsx
@@ -5716,6 +5716,7 @@ const App: React.FC = () => {
           isApiMode={isApiMode && !documentReadOnly}
           initialTab={initialExportTab}
           wrapCopiedAnnotations={wrapCopiedFeedback}
+          restoreFocusId={isCompactTouchLayout ? 'pn-compact-plan-options-trigger' : 'pn-plan-options-trigger'}
         />
 
         {/* Import Modal */}
@@ -5724,6 +5725,7 @@ const App: React.FC = () => {
           onClose={() => setShowImport(false)}
           onImport={importFromShareUrl}
           shareBaseUrl={shareBaseUrl}
+          restoreFocusId={isCompactTouchLayout ? 'pn-compact-plan-options-trigger' : 'pn-plan-options-trigger'}
         />
 
         {/* Feedback prompt dialog */}
diff --git a/packages/review-editor/components/AIConfigBar.tsx b/packages/review-editor/components/AIConfigBar.tsx
index 250683d06..e508a78b6 100644
--- a/packages/review-editor/components/AIConfigBar.tsx
+++ b/packages/review-editor/components/AIConfigBar.tsx
@@ -2,6 +2,7 @@ import type React from 'react';
 import { useState, useEffect, useRef } from 'react';
 import { getProviderMeta } from '@plannotator/ui/components/ProviderIcons';
 import { type AIProviderOption } from '@plannotator/ui/utils/aiProvider';
+import { shouldAutoFocusPassiveSearch } from '@plannotator/ui/hooks/useViewportEnvironment';
 
 interface AIConfigBarProps {
   providers: AIProviderOption[];
@@ -162,16 +163,17 @@ export const AIConfigBar: React.FC<AIConfigBarProps> = ({
             </button>
 
             {openMenu === 'model' && (
-              <div className="ai-config-menu">
+              <div data-pn-secondary-input-picker className="ai-config-menu">
                 {models.length > 8 && (
                   <div className="ai-config-menu-search">
                     <input
+                      data-pn-mobile-editable
                       ref={searchInputRef}
                       type="text"
                       placeholder="Filter models…"
                       value={modelSearch}
                       onChange={e => setModelSearch(e.target.value)}
-                      autoFocus
+                      autoFocus={shouldAutoFocusPassiveSearch()}
                     />
                   </div>
                 )}
diff --git a/packages/review-editor/components/AITab.tsx b/packages/review-editor/components/AITab.tsx
index c2ff795ab..234ee1399 100644
--- a/packages/review-editor/components/AITab.tsx
+++ b/packages/review-editor/components/AITab.tsx
@@ -309,6 +309,7 @@ const GeneralInput: React.FC<{
     <div className="border-t border-border/50 p-2">
       <div className="flex items-end gap-1.5">
         <textarea
+          data-pn-mobile-editable
           ref={textareaRef}
           value={value}
           onChange={(e) => onChange(e.target.value)}
diff --git a/packages/review-editor/components/AnnotationToolbar.tsx b/packages/review-editor/components/AnnotationToolbar.tsx
index 7850666cc..6b6fe1ae9 100644
--- a/packages/review-editor/components/AnnotationToolbar.tsx
+++ b/packages/review-editor/components/AnnotationToolbar.tsx
@@ -233,6 +233,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
               <div className="flex items-center justify-between mb-1">
                 <span className="text-[10px] text-muted-foreground">Suggested code</span>
                 <button
+                  id="pn-suggestion-editor-trigger"
                   onClick={() => setShowCodeModal(true)}
                   className="p-0.5 rounded hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
                   title="Expand editor"
@@ -243,6 +244,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
                 </button>
               </div>
               <textarea
+                data-pn-mobile-editable
                 ref={suggestedCodeRef}
                 value={suggestedCode}
                 onChange={(e) => setSuggestedCode(e.target.value)}
diff --git a/packages/review-editor/components/AskAIInput.tsx b/packages/review-editor/components/AskAIInput.tsx
index 5a0078822..ef4247d9c 100644
--- a/packages/review-editor/components/AskAIInput.tsx
+++ b/packages/review-editor/components/AskAIInput.tsx
@@ -60,6 +60,7 @@ export const AskAIInput: React.FC<AskAIInputProps> = ({
       </div>
 
       <textarea
+        data-pn-mobile-editable
         value={question}
         onChange={(e) => setQuestion(e.target.value)}
         placeholder="Ask about this code..."
diff --git a/packages/review-editor/components/BaseBranchPicker.tsx b/packages/review-editor/components/BaseBranchPicker.tsx
index ea80cf589..9e0e0a892 100644
--- a/packages/review-editor/components/BaseBranchPicker.tsx
+++ b/packages/review-editor/components/BaseBranchPicker.tsx
@@ -1,6 +1,7 @@
 import React, { useEffect, useMemo, useRef, useState } from 'react';
 import { Popover } from '@base-ui/react/popover';
 import type { AvailableBranches, CompareTargetPickerCopy, RecentCommit } from '@plannotator/shared/types';
+import { shouldAutoFocusPassiveSearch } from '@plannotator/ui/hooks/useViewportEnvironment';
 
 interface BaseBranchPickerProps {
   availableBranches: AvailableBranches;
@@ -183,11 +184,13 @@ export const BaseBranchPicker: React.FC<BaseBranchPickerProps> = ({
       <Popover.Portal>
         <Popover.Positioner side="bottom" align="start" sideOffset={4} className="z-50">
           <Popover.Popup
-            className="w-80 bg-popover text-popover-foreground border border-border rounded shadow-lg overflow-hidden origin-[var(--transform-origin)] transition-opacity data-starting-style:opacity-0 data-ending-style:opacity-0"
-            initialFocus={() => searchRef.current}
+            data-pn-secondary-input-picker
+            className="w-80 max-w-[calc(100vw-2rem)] bg-popover text-popover-foreground border border-border rounded shadow-lg overflow-hidden origin-[var(--transform-origin)] transition-opacity data-starting-style:opacity-0 data-ending-style:opacity-0"
+            initialFocus={shouldAutoFocusPassiveSearch() ? () => searchRef.current : false}
           >
           <div className="p-2 border-b border-border/50">
             <input
+              data-pn-mobile-editable
               ref={searchRef}
               type="text"
               value={query}
diff --git a/packages/review-editor/components/CallFlowSearchControls.tsx b/packages/review-editor/components/CallFlowSearchControls.tsx
index 929f1af48..599b076c5 100644
--- a/packages/review-editor/components/CallFlowSearchControls.tsx
+++ b/packages/review-editor/components/CallFlowSearchControls.tsx
@@ -35,6 +35,7 @@ export function CallFlowSearchControls({
         <Search aria-hidden="true" size={13} strokeWidth={1.75} />
         <span className="sr-only">{label}</span>
         <input
+          data-pn-mobile-editable
           ref={inputRef}
           type="search"
           value={query}
@@ -59,6 +60,8 @@ export function CallFlowSearchControls({
         {matchCount === 0 ? '0/0' : `${Math.min(currentMatchIndex + 1, matchCount)}/${matchCount}`}
       </span>
       <button
+        data-pn-touch-target
+        data-pn-touch-target-icon
         type="button"
         className="call-flow-icon-button"
         onClick={() => onMoveMatch(-1)}
@@ -69,6 +72,8 @@ export function CallFlowSearchControls({
         <ChevronUp aria-hidden="true" size={14} />
       </button>
       <button
+        data-pn-touch-target
+        data-pn-touch-target-icon
         type="button"
         className="call-flow-icon-button"
         onClick={() => onMoveMatch(1)}
@@ -79,6 +84,8 @@ export function CallFlowSearchControls({
         <ChevronDown aria-hidden="true" size={14} />
       </button>
       <button
+        data-pn-touch-target
+        data-pn-touch-target-icon
         type="button"
         className="call-flow-icon-button"
         onClick={onClose}
diff --git a/packages/review-editor/components/ExpandedCommentDialog.mobile.test.tsx b/packages/review-editor/components/ExpandedCommentDialog.mobile.test.tsx
index 5b723e0ff..6f084bd45 100644
--- a/packages/review-editor/components/ExpandedCommentDialog.mobile.test.tsx
+++ b/packages/review-editor/components/ExpandedCommentDialog.mobile.test.tsx
@@ -63,6 +63,7 @@ describe('ExpandedCommentDialog mobile composition', () => {
     const suggestButton = Array.from(document.querySelectorAll('button'))
       .find(button => button.textContent?.trim() === 'Suggest code');
     expect(suggestButton).not.toBeNull();
+    expect(suggestButton?.id).toBe('pn-suggestion-editor-trigger');
     await act(async () => suggestButton?.click());
     expect(suggestionOpens).toBe(1);
   });
diff --git a/packages/review-editor/components/ExpandedCommentDialog.tsx b/packages/review-editor/components/ExpandedCommentDialog.tsx
index 2134e566f..d5acc4674 100644
--- a/packages/review-editor/components/ExpandedCommentDialog.tsx
+++ b/packages/review-editor/components/ExpandedCommentDialog.tsx
@@ -147,6 +147,7 @@ export const ExpandedCommentDialog: React.FC<ExpandedCommentDialogProps> = ({
               )}
               {onEditSuggestion && (
                 <button
+                  id="pn-suggestion-editor-trigger"
                   type="button"
                   onClick={onEditSuggestion}
                   className="text-xs text-muted-foreground hover:text-foreground transition-colors"
diff --git a/packages/review-editor/components/FileCommentBanner.tsx b/packages/review-editor/components/FileCommentBanner.tsx
index d0fc9227e..37b130b55 100644
--- a/packages/review-editor/components/FileCommentBanner.tsx
+++ b/packages/review-editor/components/FileCommentBanner.tsx
@@ -105,6 +105,7 @@ export const FileCommentCard: React.FC<{
       {isEditing ? (
         <div className="mt-1" onClick={(e) => e.stopPropagation()}>
           <textarea
+            data-pn-mobile-editable
             autoFocus
             value={draft}
             onChange={(e) => setDraft(e.target.value)}
diff --git a/packages/review-editor/components/PRCommentsTab.tsx b/packages/review-editor/components/PRCommentsTab.tsx
index fa0560add..5e8cca1d3 100644
--- a/packages/review-editor/components/PRCommentsTab.tsx
+++ b/packages/review-editor/components/PRCommentsTab.tsx
@@ -324,6 +324,7 @@ export const PRCommentsTab: React.FC<PRCommentsTabProps> = React.memo(({ context
             <path strokeLinecap="round" strokeLinejoin="round" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
           </svg>
           <input
+            data-pn-mobile-editable
             ref={searchInputRef}
             value={searchQuery}
             onChange={(e) => setSearchQuery(e.target.value)}
diff --git a/packages/review-editor/components/PanelChrome.tsx b/packages/review-editor/components/PanelChrome.tsx
index 88705bf4f..de693a208 100644
--- a/packages/review-editor/components/PanelChrome.tsx
+++ b/packages/review-editor/components/PanelChrome.tsx
@@ -381,6 +381,7 @@ export function PanelSearchField({
           />
         </svg>
         <input
+          data-pn-mobile-editable
           ref={inputRef}
           type="text"
           value={query}
@@ -399,6 +400,8 @@ export function PanelSearchField({
             </span>
           )}
           <button
+            data-pn-touch-target
+            data-pn-touch-target-icon
             type="button"
             onClick={hasQuery ? onClear : onClose}
             className="rounded p-0.5 text-muted-foreground transition-colors hover:bg-background/50 hover:text-foreground"
diff --git a/packages/review-editor/components/SuggestionModal.mobile.test.tsx b/packages/review-editor/components/SuggestionModal.mobile.test.tsx
new file mode 100644
index 000000000..dd13d9dc9
--- /dev/null
+++ b/packages/review-editor/components/SuggestionModal.mobile.test.tsx
@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { SuggestionModal } from './SuggestionModal';
+
+const hasDom = typeof document !== 'undefined';
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = null;
+  host?.remove();
+  host = null;
+  if (hasDom) document.body.replaceChildren();
+});
+
+describe('SuggestionModal mobile containment', () => {
+  test.skipIf(!hasDom)('uses the visible viewport and compact-safe editor structure', async () => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+
+    await act(async () => {
+      root?.render(
+        <SuggestionModal
+          filePath="src/example.ts"
+          toolbarState={null}
+          selectedOriginalCode="const value = 1;"
+          suggestedCode="const value = 2;"
+          setSuggestedCode={() => {}}
+          modalLayout="horizontal"
+          setModalLayout={() => {}}
+          onClose={() => {}}
+        />,
+      );
+    });
+
+    const stage = document.querySelector<HTMLElement>('.pn-visible-viewport-overlay');
+    const dialog = document.querySelector<HTMLElement>('[role="dialog"]');
+    const panes = document.querySelector<HTMLElement>('.pn-suggestion-panes');
+    const editor = document.querySelector<HTMLTextAreaElement>('textarea');
+    const labelledButtons = document.querySelectorAll<HTMLButtonElement>('button[aria-label]');
+
+    expect(stage).not.toBeNull();
+    expect(dialog?.getAttribute('aria-modal')).toBe('true');
+    expect(dialog?.hasAttribute('aria-labelledby')).toBe(true);
+    expect(dialog?.hasAttribute('data-pn-secondary-input-dialog')).toBe(true);
+    expect(panes?.classList.contains('min-h-0')).toBe(true);
+    expect(editor?.getAttribute('data-pn-mobile-editable')).toBe('true');
+    expect(editor?.className).toContain('min-h-[300px]');
+    expect(labelledButtons.length).toBe(2);
+  });
+
+  test.skipIf(!hasDom)('delegates Escape dismissal to the dialog primitive', async () => {
+    let closeCount = 0;
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+
+    await act(async () => {
+      root?.render(
+        <SuggestionModal
+          filePath="src/example.ts"
+          toolbarState={null}
+          selectedOriginalCode="const value = 1;"
+          suggestedCode="const value = 2;"
+          setSuggestedCode={() => {}}
+          modalLayout="horizontal"
+          setModalLayout={() => {}}
+          onClose={() => { closeCount += 1; }}
+        />,
+      );
+    });
+
+    await act(async () => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    });
+
+    expect(closeCount).toBe(1);
+  });
+});
diff --git a/packages/review-editor/components/SuggestionModal.tsx b/packages/review-editor/components/SuggestionModal.tsx
index a2aa86c76..3f9e378ae 100644
--- a/packages/review-editor/components/SuggestionModal.tsx
+++ b/packages/review-editor/components/SuggestionModal.tsx
@@ -1,4 +1,5 @@
 import React from 'react';
+import { Dialog } from '@base-ui/react/dialog';
 import { HighlightedCode } from './HighlightedCode';
 import { ToolbarState } from '../hooks/useAnnotationToolbar';
 import { useTabIndent } from '../hooks/useTabIndent';
@@ -28,102 +29,129 @@ export const SuggestionModal: React.FC<SuggestionModalProps> = ({
 }) => {
   const language = detectLanguage(filePath);
   const handleTabIndent = useTabIndent(setSuggestedCode);
+  const titleId = React.useId();
+  const textareaRef = React.useRef<HTMLTextAreaElement>(null);
 
   return (
-    <div className="fixed inset-0 z-[2000] flex items-center justify-center">
-      <div className="absolute inset-0 bg-black/60 backdrop-blur-sm" />
-      <div className="relative w-[960px] max-w-[95vw] max-h-[85vh] flex flex-col bg-popover border border-border rounded-xl shadow-2xl">
-        {/* Header */}
-        <div className="flex items-center justify-between px-4 py-3 border-b border-border">
-          <div className="flex items-center gap-2">
-            <span className="text-xs font-medium text-foreground">Suggest Changes</span>
-            {language && (
-              <span className="text-[10px] font-mono px-1.5 py-0.5 rounded bg-muted text-muted-foreground">
-                {language}
-              </span>
-            )}
-            {toolbarState && (
-              <span className="text-[10px] font-mono text-muted-foreground">
-                L{Math.min(toolbarState.range.start, toolbarState.range.end)}
-                {toolbarState.range.start !== toolbarState.range.end &&
-                  `-${Math.max(toolbarState.range.start, toolbarState.range.end)}`}
-              </span>
-            )}
-          </div>
-          <div className="flex items-center gap-1">
-            {/* Layout toggle */}
-            <button
-              onClick={() => setModalLayout(modalLayout === 'horizontal' ? 'vertical' : 'horizontal')}
-              className="p-1 rounded hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
-              title={modalLayout === 'horizontal' ? 'Switch to vertical layout' : 'Switch to horizontal layout'}
-            >
-              {modalLayout === 'horizontal' ? (
-                <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                  <path strokeLinecap="round" strokeLinejoin="round" d="M4 4h16v7H4zM4 13h16v7H4z" />
-                </svg>
-              ) : (
-                <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                  <path strokeLinecap="round" strokeLinejoin="round" d="M4 4h7v16H4zM13 4h7v16h-7z" />
-                </svg>
-              )}
-            </button>
-            <button
-              onClick={onClose}
-              className="p-1 rounded hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
-            >
-              <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
-              </svg>
-            </button>
-          </div>
-        </div>
-
-        {/* Two-pane layout */}
-        <div className={`flex flex-1 min-h-0 ${modalLayout === 'vertical' ? 'flex-col' : ''}`}>
-          {/* Original code (read-only) */}
-          <div className={`flex-1 flex flex-col min-w-0 min-h-0 ${modalLayout === 'vertical' ? 'border-b border-border' : 'border-r border-border'}`}>
-            <div className="px-3 py-1.5 border-b border-border/50 bg-muted/30">
-              <span className="text-[10px] font-medium text-muted-foreground uppercase tracking-wider">Original</span>
+    <Dialog.Root
+      open
+      onOpenChange={(open) => {
+        if (!open) onClose();
+      }}
+    >
+      <Dialog.Portal>
+        <Dialog.Backdrop className="fixed inset-0 z-[1999] bg-black/60 backdrop-blur-sm" />
+        <div className="pn-visible-viewport-overlay pointer-events-none z-[2000] flex items-center justify-center">
+          <Dialog.Popup
+            data-pn-secondary-input-dialog
+            aria-modal="true"
+            aria-labelledby={titleId}
+            initialFocus={() => textareaRef.current}
+            finalFocus={false}
+            className="pn-suggestion-dialog pointer-events-auto relative flex min-h-0 flex-col overflow-hidden rounded-xl border border-border bg-popover shadow-2xl"
+          >
+            {/* Header */}
+            <div className="flex shrink-0 items-center justify-between border-b border-border px-4 py-3">
+              <div className="flex items-center gap-2">
+                <Dialog.Title id={titleId} className="text-xs font-medium text-foreground">
+                  Suggest Changes
+                </Dialog.Title>
+                {language && (
+                  <span className="text-[10px] font-mono px-1.5 py-0.5 rounded bg-muted text-muted-foreground">
+                    {language}
+                  </span>
+                )}
+                {toolbarState && (
+                  <span className="text-[10px] font-mono text-muted-foreground">
+                    L{Math.min(toolbarState.range.start, toolbarState.range.end)}
+                    {toolbarState.range.start !== toolbarState.range.end &&
+                      `-${Math.max(toolbarState.range.start, toolbarState.range.end)}`}
+                  </span>
+                )}
+              </div>
+              <div className="flex items-center gap-1">
+                {/* Layout toggle */}
+                <button
+                  type="button"
+                  onClick={() => setModalLayout(modalLayout === 'horizontal' ? 'vertical' : 'horizontal')}
+                  className="pn-suggestion-layout-toggle rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                  title={modalLayout === 'horizontal' ? 'Switch to vertical layout' : 'Switch to horizontal layout'}
+                  aria-label={modalLayout === 'horizontal' ? 'Switch to vertical layout' : 'Switch to horizontal layout'}
+                >
+                  {modalLayout === 'horizontal' ? (
+                    <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M4 4h16v7H4zM4 13h16v7H4z" />
+                    </svg>
+                  ) : (
+                    <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M4 4h7v16H4zM13 4h7v16h-7z" />
+                    </svg>
+                  )}
+                </button>
+                <Dialog.Close
+                  render={
+                    <button
+                      type="button"
+                      className="p-1 rounded hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
+                      aria-label="Close code suggestion"
+                    />
+                  }
+                >
+                  <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                  </svg>
+                </Dialog.Close>
+              </div>
             </div>
-            <pre className="flex-1 overflow-auto p-3 m-0 text-xs leading-relaxed suggestion-modal-original">
-              <HighlightedCode code={selectedOriginalCode || '(no lines selected)'} language={language} />
-            </pre>
-          </div>
 
-          {/* Suggested code input */}
-          <div className="flex-1 flex flex-col min-w-0 min-h-0">
-            <div className="px-3 py-1.5 border-b border-border/50 bg-muted/30">
-              <span className="text-[10px] font-medium text-success uppercase tracking-wider">Suggestion</span>
+            {/* Two-pane layout */}
+            <div className={`pn-suggestion-panes flex min-h-0 flex-1 ${modalLayout === 'vertical' ? 'flex-col' : ''}`}>
+              {/* Original code (read-only) */}
+              <div className={`pn-suggestion-original flex min-h-0 min-w-0 flex-1 flex-col ${modalLayout === 'vertical' ? 'border-b border-border' : 'border-r border-border'}`}>
+                <div className="px-3 py-1.5 border-b border-border/50 bg-muted/30">
+                  <span className="text-[10px] font-medium text-muted-foreground uppercase tracking-wider">Original</span>
+                </div>
+                <pre className="flex-1 overflow-auto p-3 m-0 text-xs leading-relaxed suggestion-modal-original">
+                  <HighlightedCode code={selectedOriginalCode || '(no lines selected)'} language={language} />
+                </pre>
+              </div>
+
+              {/* Suggested code input */}
+              <div className="flex-1 flex flex-col min-w-0 min-h-0">
+                <div className="px-3 py-1.5 border-b border-border/50 bg-muted/30">
+                  <span className="text-[10px] font-medium text-success uppercase tracking-wider">Suggestion</span>
+                </div>
+                <textarea
+                  data-pn-mobile-editable
+                  ref={textareaRef}
+                  value={suggestedCode}
+                  onChange={(e) => setSuggestedCode(e.target.value)}
+                  placeholder={selectedOriginalCode || 'Enter code suggestion...'}
+                  className="suggested-code-input flex-1 rounded-none border-0 min-h-[300px]"
+                  spellCheck={false}
+                  onKeyDown={(e) => {
+                    if (e.key === 'Tab') {
+                      handleTabIndent(e);
+                    }
+                  }}
+                />
+              </div>
             </div>
-            <textarea
-              value={suggestedCode}
-              onChange={(e) => setSuggestedCode(e.target.value)}
-              placeholder={selectedOriginalCode || 'Enter code suggestion...'}
-              className="suggested-code-input flex-1 rounded-none border-0 min-h-[300px]"
-              autoFocus
-              spellCheck={false}
-              onKeyDown={(e) => {
-                if (e.key === 'Escape') {
-                  onClose();
-                } else if (e.key === 'Tab') {
-                  handleTabIndent(e);
-                }
-              }}
-            />
-          </div>
-        </div>
 
-        {/* Footer */}
-        <div className="flex items-center justify-between px-4 py-3 border-t border-border">
-          <span className="text-[10px] text-muted-foreground">Tip: Edit the suggestion based on the original code on the left</span>
-          <button
-            onClick={onClose}
-            className="review-toolbar-btn primary"
-          >
-            Done
-          </button>
+            {/* Footer */}
+            <div className="flex shrink-0 items-center justify-between border-t border-border px-4 py-3">
+              <span className="hidden text-[10px] text-muted-foreground sm:block">
+                Tip: Edit the suggestion based on the original code on the left
+              </span>
+              <Dialog.Close
+                render={<button type="button" className="review-toolbar-btn primary ml-auto" />}
+              >
+                Done
+              </Dialog.Close>
+            </div>
+          </Dialog.Popup>
         </div>
-      </div>
-    </div>
+      </Dialog.Portal>
+    </Dialog.Root>
   );
 };
diff --git a/packages/review-editor/components/ToolbarHost.tsx b/packages/review-editor/components/ToolbarHost.tsx
index e53283af5..d107fc0a6 100644
--- a/packages/review-editor/components/ToolbarHost.tsx
+++ b/packages/review-editor/components/ToolbarHost.tsx
@@ -1,4 +1,4 @@
-import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo } from 'react';
+import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef } from 'react';
 import type {
   CodeAnnotation,
   CodeAnnotationType,
@@ -86,6 +86,7 @@ export const ToolbarHost = forwardRef<ToolbarHostHandle, ToolbarHostProps>(funct
   const conventionalCommentsEnabled = useConfigValue('conventionalComments');
   const conventionalLabelsJson = useConfigValue('conventionalLabels');
   const enabledLabels = useMemo(() => getEnabledLabels(conventionalLabelsJson), [conventionalLabelsJson]);
+  const restoreSuggestionFocusRef = useRef(false);
 
   // Replaces the parent's `onMouseMove={toolbar.handleMouseMove}` on its scroll
   // container — the hook only stashes clientX/Y for toolbar placement, so a
@@ -107,7 +108,18 @@ export const ToolbarHost = forwardRef<ToolbarHostHandle, ToolbarHostProps>(funct
     [toolbar.handleLineSelectionEnd, toolbar.openLineAnnotation, toolbar.handleTokenClick, toolbar.startEdit],
   );
 
-  const handleCloseCodeModal = useCallback(() => toolbar.setShowCodeModal(false), [toolbar.setShowCodeModal]);
+  const handleCloseCodeModal = useCallback(() => {
+    restoreSuggestionFocusRef.current = true;
+    toolbar.setShowCodeModal(false);
+  }, [toolbar.setShowCodeModal]);
+  useEffect(() => {
+    if (toolbar.showCodeModal || !restoreSuggestionFocusRef.current) return;
+    restoreSuggestionFocusRef.current = false;
+    const frame = requestAnimationFrame(() => {
+      document.getElementById('pn-suggestion-editor-trigger')?.focus({ preventScroll: true });
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [toolbar.showCodeModal]);
   const handleCollapseCommentModal = useCallback(() => {
     if (toolbar.expandedComposerRequired) {
       toolbar.handleDismiss();
diff --git a/packages/review-editor/components/WorktreePicker.tsx b/packages/review-editor/components/WorktreePicker.tsx
index 1d7caf596..d70bcc075 100644
--- a/packages/review-editor/components/WorktreePicker.tsx
+++ b/packages/review-editor/components/WorktreePicker.tsx
@@ -1,6 +1,7 @@
 import React, { useMemo, useRef, useState } from 'react';
 import { Popover } from '@base-ui/react/popover';
 import type { WorktreeInfo } from '@plannotator/shared/types';
+import { shouldAutoFocusPassiveSearch } from '@plannotator/ui/hooks/useViewportEnvironment';
 
 interface WorktreePickerProps {
   worktrees: WorktreeInfo[];
@@ -92,8 +93,9 @@ export const WorktreePicker: React.FC<WorktreePickerProps> = ({
       <Popover.Portal>
         <Popover.Positioner side="bottom" align="start" sideOffset={4} className="z-50">
           <Popover.Popup
-            className="w-72 bg-popover text-popover-foreground border border-border rounded shadow-lg overflow-hidden origin-[var(--transform-origin)] transition-opacity data-starting-style:opacity-0 data-ending-style:opacity-0"
-            initialFocus={() => {
+            data-pn-secondary-input-picker
+            className="w-72 max-w-[calc(100vw-2rem)] bg-popover text-popover-foreground border border-border rounded shadow-lg overflow-hidden origin-[var(--transform-origin)] transition-opacity data-starting-style:opacity-0 data-ending-style:opacity-0"
+            initialFocus={shouldAutoFocusPassiveSearch() ? () => {
               // Only override the default focus when the search input is
               // actually rendered — otherwise arrow keys would bubble out to
               // the file-tree nav. For short worktree lists, returning null
@@ -101,11 +103,12 @@ export const WorktreePicker: React.FC<WorktreePickerProps> = ({
               // tabbable); undefined would mean "do nothing" and leave focus
               // on the trigger.
               return searchRef.current;
-            }}
+            } : false}
           >
           {worktrees.length > 3 && (
             <div className="p-2 border-b border-border/50">
               <input
+                data-pn-mobile-editable
                 ref={searchRef}
                 type="text"
                 value={query}
diff --git a/packages/review-editor/components/guide/GuideEmptyState.tsx b/packages/review-editor/components/guide/GuideEmptyState.tsx
index 13f37e703..1b0a25f7d 100644
--- a/packages/review-editor/components/guide/GuideEmptyState.tsx
+++ b/packages/review-editor/components/guide/GuideEmptyState.tsx
@@ -17,6 +17,7 @@ import {
 } from '@plannotator/ui/components/AgentsTab';
 import { groupModelOptions, labelWithinGroup, SEARCHABLE_THRESHOLD } from '@plannotator/ui/components/AgentControls';
 import { useGuideLaunch } from '../../hooks/guide/useGuideLaunch';
+import { shouldAutoFocusPassiveSearch } from '@plannotator/ui/hooks/useViewportEnvironment';
 
 type Option = { value: string; label: string };
 
@@ -84,14 +85,16 @@ function InlinePicker({
         <>
           <div className="fixed inset-0 z-10" onClick={close} />
           <div
-            className={`absolute left-0 top-full z-20 mt-1 rounded-lg border border-border/50 bg-popover shadow-xl ${
+            data-pn-secondary-input-picker
+            className={`absolute left-0 top-full z-20 mt-1 max-w-[calc(100vw-2rem)] rounded-lg border border-border/50 bg-popover shadow-xl ${
               searchable ? 'w-[340px]' : 'min-w-[140px]'
             }`}
           >
             {searchable && (
               <div className="p-1 pb-0">
                 <input
-                  autoFocus
+                  data-pn-mobile-editable
+                  autoFocus={shouldAutoFocusPassiveSearch()}
                   value={query}
                   onChange={(e) => setQuery(e.target.value)}
                   onKeyDown={(e) => {
@@ -443,6 +446,7 @@ export const GuideEmptyState: React.FC<GuideEmptyStateProps> = ({ capabilities,
           {showOutput && capturedPayload !== null && (
             <div className="mt-2.5 w-full">
               <textarea
+                data-pn-mobile-editable
                 value={editedPayload}
                 onChange={(e) => setEditedPayload(e.target.value)}
                 spellCheck={false}
@@ -515,6 +519,7 @@ export const GuideEmptyState: React.FC<GuideEmptyStateProps> = ({ capabilities,
             {showInstructions && (
               <div className="mt-1.5 max-w-[560px]">
                 <textarea
+                  data-pn-mobile-editable
                   value={instructions}
                   onChange={(e) => handleInstructionsChange(e.target.value)}
                   maxLength={GUIDE_EXTRA_INSTRUCTIONS_MAX_CHARS}
diff --git a/packages/ui/components/AgentControls.tsx b/packages/ui/components/AgentControls.tsx
index 90a901d46..fcea5a353 100644
--- a/packages/ui/components/AgentControls.tsx
+++ b/packages/ui/components/AgentControls.tsx
@@ -1,6 +1,7 @@
 import React, { useState } from 'react';
 import { ChevronDown, Plus } from 'lucide-react';
 import { cn } from '../lib/utils';
+import { shouldAutoFocusPassiveSearch } from '../hooks/useViewportEnvironment';
 
 // --- Launch-control primitives (ported from the prototype's sidebar) ---
 
@@ -143,15 +144,17 @@ export function SelectMenu({ value, options, onChange, icon, placeholder, footer
         <>
           <div className="fixed inset-0 z-10" onClick={close} />
           <div
+            data-pn-secondary-input-picker
             className={cn(
-              'absolute right-0 top-full left-0 z-20 mt-1 rounded-xl bg-card shadow-[var(--card-shadow)] ring-1 ring-border/20',
+              'absolute right-0 top-full left-0 z-20 mt-1 max-w-[calc(100vw-2rem)] rounded-xl bg-card shadow-[var(--card-shadow)] ring-1 ring-border/20',
               searchable && 'min-w-[240px]',
             )}
           >
             {searchable && (
               <div className="p-1 pb-0">
                 <input
-                  autoFocus
+                  data-pn-mobile-editable
+                  autoFocus={shouldAutoFocusPassiveSearch()}
                   value={query}
                   onChange={(e) => setQuery(e.target.value)}
                   onKeyDown={(e) => {
diff --git a/packages/ui/components/AgentsTab.tsx b/packages/ui/components/AgentsTab.tsx
index cfd7da72b..b810d87d6 100644
--- a/packages/ui/components/AgentsTab.tsx
+++ b/packages/ui/components/AgentsTab.tsx
@@ -1,4 +1,5 @@
-import React, { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+import React, { useState, useEffect, useMemo, useCallback, useId, useRef } from 'react';
+import { createPortal } from 'react-dom';
 import {
   Bot,
   Play,
@@ -24,6 +25,8 @@ import type { AgentEngine, AgentMode, ReviewEngine } from '../hooks/useAgentSett
 import type { AgentLaunchParams } from '../hooks/useAgentJobs';
 import { ConfigRow, SegmentedPicker, Toggle, SelectMenu } from './AgentControls';
 import { CODEX_MODELS, CODEX_EFFORT_LABELS, codexReasoningOptions } from '../utils/codexModels';
+import { shouldAutoFocusPassiveSearch } from '../hooks/useViewportEnvironment';
+import { useModalFocusLifecycle } from '../hooks/useModalFocusLifecycle';
 
 export type { AgentLaunchParams } from '../hooks/useAgentJobs';
 
@@ -274,6 +277,9 @@ function AddReviewDialog({
   const [query, setQuery] = useState('');
   const [busy, setBusy] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const titleId = useId();
+
+  useModalFocusLifecycle(true, onClose);
 
   useEffect(() => {
     let alive = true;
@@ -317,13 +323,19 @@ function AddReviewDialog({
     }
   };
 
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center p-4" role="dialog" aria-modal="true">
+  return createPortal(
+    <div className="pn-visible-viewport-overlay z-50 flex items-center justify-center">
       <div className="absolute inset-0 bg-black/40" onClick={onClose} />
-      <div className="relative z-10 flex max-h-[70vh] w-full max-w-sm flex-col overflow-hidden rounded-xl bg-card shadow-[var(--card-shadow)] ring-1 ring-border/20">
+      <div
+        data-pn-secondary-input-dialog
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        className="relative z-10 flex max-h-[min(70vh,100%)] w-full max-w-sm flex-col overflow-hidden rounded-xl bg-card shadow-[var(--card-shadow)] ring-1 ring-border/20"
+      >
         <div className="flex items-center justify-between border-b border-border/40 px-3 py-2.5">
-          <span className="text-[12px] font-medium text-foreground">Add a review</span>
-          <button type="button" onClick={onClose} className="text-muted-foreground/50 hover:text-foreground">
+          <span id={titleId} className="text-[12px] font-medium text-foreground">Add a review</span>
+          <button type="button" onClick={onClose} className="text-muted-foreground/50 hover:text-foreground" aria-label="Close add review">
             <X size={13} />
           </button>
         </div>
@@ -332,7 +344,8 @@ function AddReviewDialog({
           <div className="flex items-center gap-2 rounded-lg border border-border/30 bg-surface-1/30 px-2.5 py-1.5">
             <Search className="shrink-0 text-muted-foreground/40" size={12} />
             <input
-              autoFocus
+              data-pn-mobile-editable
+              autoFocus={shouldAutoFocusPassiveSearch()}
               value={query}
               onChange={(e) => setQuery(e.target.value)}
               placeholder="Filter your skills"
@@ -369,7 +382,8 @@ function AddReviewDialog({
 
         {error && <p className="border-t border-border/40 px-3 py-2 text-[10px] text-red-500">{error}</p>}
       </div>
-    </div>
+    </div>,
+    document.body,
   );
 }
 
diff --git a/packages/ui/components/AttachmentsButton.tsx b/packages/ui/components/AttachmentsButton.tsx
index b74a67ffd..0a7c36a3d 100644
--- a/packages/ui/components/AttachmentsButton.tsx
+++ b/packages/ui/components/AttachmentsButton.tsx
@@ -343,6 +343,7 @@ export const AttachmentsButton: React.FC<AttachmentsButtonProps> = ({
               {/* Manual path input */}
               <div className="flex gap-2">
                 <input
+                  data-pn-mobile-editable
                   type="text"
                   value={manualPath}
                   onChange={(e) => setManualPath(e.target.value)}
diff --git a/packages/ui/components/CodeFilePopout.tsx b/packages/ui/components/CodeFilePopout.tsx
index 950e74700..9ccc7bf38 100644
--- a/packages/ui/components/CodeFilePopout.tsx
+++ b/packages/ui/components/CodeFilePopout.tsx
@@ -218,6 +218,7 @@ const CodeInlineAnnotation: React.FC<{
       {isEditing ? (
         <div className="mt-2 space-y-2">
           <textarea
+            data-pn-mobile-editable
             ref={textareaRef}
             value={editText}
             onChange={(e) => setEditText(e.target.value)}
@@ -479,7 +480,7 @@ export const CodeFilePopout: React.FC<CodeFilePopoutProps> = ({
         onClose={onClose}
         title={requestedPath ?? displayName}
         container={container}
-        className="w-[min(520px,calc(100vw-4rem))]"
+        className="w-[min(520px,calc(var(--pn-viewport-width,100vw)-4rem))]"
       >
         <div className="flex flex-col gap-2 px-5 py-6 text-sm">
           <div className="font-medium text-foreground">{error}</div>
@@ -503,7 +504,7 @@ export const CodeFilePopout: React.FC<CodeFilePopoutProps> = ({
       onClose={onClose}
       title={displayName}
       container={container}
-      className="w-[calc(100vw-4rem)] max-w-[min(calc(100vw-4rem),1500px)] h-[calc(100vh-4rem)]"
+      className="h-[calc(var(--pn-viewport-height,100vh)-4rem)] w-[calc(var(--pn-viewport-width,100vw)-4rem)] max-w-[min(calc(var(--pn-viewport-width,100vw)-4rem),1500px)]"
     >
       <div className="flex items-center gap-3 px-5 pt-4 pb-3 pr-12">
         <div className="flex items-center gap-2 min-w-0">
diff --git a/packages/ui/components/ExportModal.tsx b/packages/ui/components/ExportModal.tsx
index 33e7ae3eb..6962855ec 100644
--- a/packages/ui/components/ExportModal.tsx
+++ b/packages/ui/components/ExportModal.tsx
@@ -6,13 +6,14 @@
  * Notes tab: Save plan to Obsidian/Bear without approving
  */
 
-import React, { useState, useEffect } from 'react';
+import React, { useId, useState, useEffect } from 'react';
 import { getObsidianSettings, getEffectiveVaultPath } from '../utils/obsidian';
 import { getBearSettings } from '../utils/bear';
 import { getOctarineSettings } from '../utils/octarine';
 import { wrapFeedbackForAgent } from '../utils/parser';
 import { copyTextToClipboard } from '../utils/clipboard';
 import { OverlayScrollArea } from './OverlayScrollArea';
+import { useModalFocusLifecycle } from '../hooks/useModalFocusLifecycle';
 
 /** POST body shape sent to the notes endpoint (mirrors what the Notes tab builds today). */
 interface SaveToNotesPayload {
@@ -65,6 +66,7 @@ interface ExportModalProps {
    * plan-review behavior).
    */
   wrapCopiedAnnotations?: (feedback: string) => string;
+  restoreFocusId?: string;
 }
 
 type Tab = 'share' | 'annotations' | 'notes';
@@ -90,12 +92,16 @@ export const ExportModal: React.FC<ExportModalProps> = ({
   initialTab,
   onSaveToNotes = defaultSaveToNotes,
   wrapCopiedAnnotations = wrapFeedbackForAgent,
+  restoreFocusId,
 }) => {
   const defaultTab = initialTab || (sharingEnabled ? 'share' : 'annotations');
   const [activeTab, setActiveTab] = useState<Tab>(defaultTab);
   const [copied, setCopied] = useState<'short' | 'full' | 'annotations' | false>(false);
   const [saveStatus, setSaveStatus] = useState<Record<SaveTarget, SaveStatus>>({ obsidian: 'idle', bear: 'idle', octarine: 'idle' });
   const [saveErrors, setSaveErrors] = useState<Record<string, string>>({});
+  const titleId = useId();
+
+  useModalFocusLifecycle(isOpen, onClose, { fallbackFocusId: restoreFocusId });
 
   // Reset tab when modal opens
   useEffect(() => {
@@ -209,9 +215,13 @@ export const ExportModal: React.FC<ExportModalProps> = ({
   const showTabs = sharingEnabled || showNotesTab;
 
   return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center bg-background/80 backdrop-blur-sm p-4">
+    <div className="pn-visible-viewport-overlay z-50 flex items-center justify-center bg-background/80 backdrop-blur-sm">
       <div
-        className="bg-card border border-border rounded-xl w-full max-w-2xl flex flex-col max-h-[80vh] shadow-2xl relative"
+        data-pn-secondary-input-dialog
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        className="relative flex max-h-[min(80vh,100%)] w-full max-w-2xl flex-col overflow-hidden rounded-xl border border-border bg-card shadow-2xl"
         onClick={e => e.stopPropagation()}
       >
         {taterSprite}
@@ -219,14 +229,16 @@ export const ExportModal: React.FC<ExportModalProps> = ({
         {/* Header */}
         <div className="p-4 border-b border-border">
           <div className="flex justify-between items-center">
-            <h3 className="font-semibold text-sm">Export</h3>
+            <h3 id={titleId} className="font-semibold text-sm">Export</h3>
             <div className="flex items-center gap-3">
               <span className="text-xs text-muted-foreground">
                 {annotationCount} annotation{annotationCount !== 1 ? 's' : ''}
               </span>
               <button
+                type="button"
                 onClick={onClose}
                 className="p-1.5 rounded-md hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
+                aria-label="Close export"
               >
                 <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
                   <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
@@ -290,6 +302,7 @@ export const ExportModal: React.FC<ExportModalProps> = ({
                   </label>
                   <div className="relative group">
                     <input
+                      data-pn-mobile-editable
                       readOnly
                       value={shortShareUrl}
                       className="w-full bg-muted rounded-lg p-3 pr-20 text-xs font-mono focus:outline-none focus:ring-2 focus:ring-accent/50"
@@ -353,6 +366,7 @@ export const ExportModal: React.FC<ExportModalProps> = ({
                 </label>
                 <div className="relative group">
                   <textarea
+                    data-pn-mobile-editable
                     readOnly
                     value={shareUrl}
                     className="w-full h-24 bg-muted rounded-lg p-3 pr-20 text-xs font-mono resize-none focus:outline-none focus:ring-2 focus:ring-accent/50"
diff --git a/packages/ui/components/ImageAnnotator/index.tsx b/packages/ui/components/ImageAnnotator/index.tsx
index 02a4609f2..bb2c22e3c 100644
--- a/packages/ui/components/ImageAnnotator/index.tsx
+++ b/packages/ui/components/ImageAnnotator/index.tsx
@@ -4,6 +4,7 @@ import { Toolbar } from './Toolbar';
 import { renderStroke } from './utils';
 import type { Point, AnnotatorState } from './types';
 import { DEFAULT_STATE } from './types';
+import { useModalFocusLifecycle } from '../../hooks/useModalFocusLifecycle';
 
 interface ImageAnnotatorProps {
   imageSrc: string;
@@ -27,6 +28,11 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
   const imageRef = useRef<HTMLImageElement | null>(null);
   const nameInputRef = useRef<HTMLInputElement>(null);
 
+  // This surface already gives Escape a two-stage meaning (blur the name
+  // field, then accept). Reuse only the focus-restoration half of the legacy
+  // modal lifecycle so that behavior remains intact.
+  useModalFocusLifecycle(isOpen, onClose, { dismissOnEscape: false });
+
   // Reset state when dialog opens
   useEffect(() => {
     if (isOpen) {
@@ -200,12 +206,16 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
 
   return (
     <div
-      className="fixed inset-0 z-[200] flex items-center justify-center bg-background/90 backdrop-blur-sm"
+      data-pn-secondary-input-dialog
+      className="pn-visible-viewport-overlay z-[200] flex items-center justify-center bg-background/90 backdrop-blur-sm"
       data-popover-layer
       onClick={handleBackdropClick}
+      role="dialog"
+      aria-modal="true"
+      aria-label="Annotate image"
     >
       {/* Canvas with image and toolbar */}
-      <div className="relative flex flex-col items-center gap-3" onClick={(e) => e.stopPropagation()}>
+      <div className="relative flex max-h-full max-w-full flex-col items-center gap-3 overflow-y-auto overscroll-contain" onClick={(e) => e.stopPropagation()}>
         {/* Toolbar - above image */}
         <Toolbar
           tool={state.tool}
@@ -237,6 +247,7 @@ export const ImageAnnotator: React.FC<ImageAnnotatorProps> = ({
           <div className="flex items-center gap-2 w-full max-w-xs">
             <label className="text-xs text-muted-foreground whitespace-nowrap">Name</label>
             <input
+              data-pn-mobile-editable
               ref={nameInputRef}
               type="text"
               value={name}
diff --git a/packages/ui/components/ImportModal.mobile.test.tsx b/packages/ui/components/ImportModal.mobile.test.tsx
new file mode 100644
index 000000000..b7c4749be
--- /dev/null
+++ b/packages/ui/components/ImportModal.mobile.test.tsx
@@ -0,0 +1,131 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import React, { act, useState } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { ImportModal } from './ImportModal';
+
+const hasDom = typeof document !== 'undefined';
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = null;
+  host?.remove();
+  host = null;
+  if (hasDom) document.body.replaceChildren();
+});
+
+describe('ImportModal mobile input shell', () => {
+  test.skipIf(!hasDom)('bounds the dialog to the visible viewport and marks its editor', async () => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+
+    await act(async () => {
+      root?.render(
+        <ImportModal
+          isOpen
+          onClose={() => {}}
+          onImport={async () => ({ success: true, count: 0, planTitle: 'Plan' })}
+        />,
+      );
+    });
+
+    const stage = host.querySelector<HTMLElement>('.pn-visible-viewport-overlay');
+    const dialog = host.querySelector<HTMLElement>('[role="dialog"]');
+    const body = host.querySelector<HTMLElement>('.overscroll-contain');
+    const input = host.querySelector<HTMLInputElement>('input');
+
+    expect(stage).not.toBeNull();
+    expect(dialog?.getAttribute('aria-modal')).toBe('true');
+    expect(dialog?.hasAttribute('data-pn-secondary-input-dialog')).toBe(true);
+    expect(dialog?.className).toContain('max-h-full');
+    expect(body?.className).toContain('overflow-y-auto');
+    expect(input?.getAttribute('data-pn-mobile-editable')).toBe('true');
+  });
+
+  test.skipIf(!hasDom)('dismisses with Escape and restores the opener focus', async () => {
+    function Harness() {
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <button type="button" onClick={() => setOpen(true)}>Open import</button>
+          <ImportModal
+            isOpen={open}
+            onClose={() => setOpen(false)}
+            onImport={async () => ({ success: true, count: 0, planTitle: 'Plan' })}
+          />
+        </>
+      );
+    }
+
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+    await act(async () => root?.render(<Harness />));
+
+    const opener = host.querySelector<HTMLButtonElement>('button');
+    opener?.focus();
+    await act(async () => opener?.click());
+    expect(document.querySelector('[role="dialog"]')).not.toBeNull();
+
+    await act(async () => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    });
+    await new Promise<void>((resolve) => {
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+
+    expect(document.querySelector('[role="dialog"]')).toBeNull();
+    expect(document.activeElement).toBe(opener);
+  });
+
+  test.skipIf(!hasDom)('restores the stable menu trigger when the transient opener unmounts', async () => {
+    function Harness() {
+      const [menuOpen, setMenuOpen] = useState(true);
+      const [modalOpen, setModalOpen] = useState(false);
+      return (
+        <>
+          <button id="pn-plan-options-trigger" type="button">Options</button>
+          {menuOpen && (
+            <button
+              type="button"
+              onClick={() => {
+                setMenuOpen(false);
+                setModalOpen(true);
+              }}
+            >
+              Import
+            </button>
+          )}
+          <ImportModal
+            isOpen={modalOpen}
+            restoreFocusId="pn-plan-options-trigger"
+            onClose={() => setModalOpen(false)}
+            onImport={async () => ({ success: true, count: 0, planTitle: 'Plan' })}
+          />
+        </>
+      );
+    }
+
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+    await act(async () => root?.render(<Harness />));
+
+    const transientOpener = Array.from(host.querySelectorAll<HTMLButtonElement>('button'))
+      .find((button) => button.textContent === 'Import');
+    transientOpener?.focus();
+    await act(async () => transientOpener?.click());
+
+    await act(async () => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    });
+    await new Promise<void>((resolve) => {
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+
+    expect(document.activeElement?.id).toBe('pn-plan-options-trigger');
+  });
+});
diff --git a/packages/ui/components/ImportModal.tsx b/packages/ui/components/ImportModal.tsx
index f008a5544..91e81f5f7 100644
--- a/packages/ui/components/ImportModal.tsx
+++ b/packages/ui/components/ImportModal.tsx
@@ -2,14 +2,16 @@
  * Import Modal for loading teammate annotations from a share URL
  */
 
-import React, { useState, useRef } from 'react';
+import React, { useCallback, useId, useState, useRef } from 'react';
 import type { ImportResult } from '../hooks/useSharing';
+import { useModalFocusLifecycle } from '../hooks/useModalFocusLifecycle';
 
 interface ImportModalProps {
   isOpen: boolean;
   onClose: () => void;
   onImport: (url: string) => Promise<ImportResult>;
   shareBaseUrl?: string;
+  restoreFocusId?: string;
 }
 
 export const ImportModal: React.FC<ImportModalProps> = ({
@@ -17,11 +19,25 @@ export const ImportModal: React.FC<ImportModalProps> = ({
   onClose,
   onImport,
   shareBaseUrl,
+  restoreFocusId,
 }) => {
   const [url, setUrl] = useState('');
   const [loading, setLoading] = useState(false);
   const [result, setResult] = useState<ImportResult | null>(null);
   const autoCloseTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const titleId = useId();
+
+  const handleClose = useCallback(() => {
+    if (autoCloseTimer.current) {
+      clearTimeout(autoCloseTimer.current);
+      autoCloseTimer.current = null;
+    }
+    setUrl('');
+    setResult(null);
+    onClose();
+  }, [onClose]);
+
+  useModalFocusLifecycle(isOpen, handleClose, { fallbackFocusId: restoreFocusId });
 
   if (!isOpen) return null;
 
@@ -43,16 +59,6 @@ export const ImportModal: React.FC<ImportModalProps> = ({
     }
   };
 
-  const handleClose = () => {
-    if (autoCloseTimer.current) {
-      clearTimeout(autoCloseTimer.current);
-      autoCloseTimer.current = null;
-    }
-    setUrl('');
-    setResult(null);
-    onClose();
-  };
-
   const handleKeyDown = (e: React.KeyboardEvent) => {
     if (e.key === 'Enter' && !loading) {
       handleImport();
@@ -60,18 +66,24 @@ export const ImportModal: React.FC<ImportModalProps> = ({
   };
 
   return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center bg-background/80 backdrop-blur-sm p-4">
+    <div className="pn-visible-viewport-overlay z-50 flex items-center justify-center bg-background/80 backdrop-blur-sm">
       <div
-        className="bg-card border border-border rounded-xl w-full max-w-lg flex flex-col shadow-2xl"
+        data-pn-secondary-input-dialog
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        className="flex max-h-full w-full max-w-lg flex-col overflow-hidden rounded-xl border border-border bg-card shadow-2xl"
         onClick={e => e.stopPropagation()}
       >
         {/* Header */}
         <div className="p-4 border-b border-border">
           <div className="flex justify-between items-center">
-            <h3 className="font-semibold text-sm">Import Teammate Review</h3>
+            <h3 id={titleId} className="font-semibold text-sm">Import Teammate Review</h3>
             <button
+              type="button"
               onClick={handleClose}
               className="p-1.5 rounded-md hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
+              aria-label="Close import review"
             >
               <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
                 <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
@@ -81,12 +93,13 @@ export const ImportModal: React.FC<ImportModalProps> = ({
         </div>
 
         {/* Body */}
-        <div className="p-4 space-y-4">
+        <div className="min-h-0 flex-1 space-y-4 overflow-y-auto overscroll-contain p-4">
           <div>
             <label className="block text-xs font-medium text-muted-foreground mb-2">
               Plannotator Share Link
             </label>
             <input
+              data-pn-mobile-editable
               type="text"
               value={url}
               onChange={e => setUrl(e.target.value)}
@@ -127,12 +140,14 @@ export const ImportModal: React.FC<ImportModalProps> = ({
         {/* Footer */}
         <div className="p-4 border-t border-border flex justify-end gap-2">
           <button
+            type="button"
             onClick={handleClose}
             className="px-3 py-1.5 rounded-md text-xs font-medium bg-muted hover:bg-muted/80 transition-colors"
           >
             Cancel
           </button>
           <button
+            type="button"
             onClick={handleImport}
             disabled={!url.trim() || loading}
             className="px-3 py-1.5 rounded-md text-xs font-medium bg-primary text-primary-foreground hover:opacity-90 transition-opacity disabled:opacity-50 disabled:cursor-not-allowed"
diff --git a/packages/ui/components/MarkdownEditor.extensions.test.tsx b/packages/ui/components/MarkdownEditor.extensions.test.tsx
index ab9b63404..103b0977f 100644
--- a/packages/ui/components/MarkdownEditor.extensions.test.tsx
+++ b/packages/ui/components/MarkdownEditor.extensions.test.tsx
@@ -59,8 +59,10 @@ describe('MarkdownEditor shim: extensions passthrough', () => {
       // The editorAttributes facet writes onto the editor's outer DOM element —
       // reachable only if the engine composed our extension into its state.
       const probed = host.querySelector('[data-extensions-probe="reached-engine"]');
+      const mobileEditableSurface = host.querySelector('[data-pn-mobile-editable-surface="true"]');
       expect(probed).not.toBeNull();
       expect(probed?.classList.contains('cm-editor')).toBe(true);
+      expect(mobileEditableSurface?.contains(probed)).toBe(true);
 
       // Byte fidelity is unaffected by a decoration-only consumer extension.
       expect(handleRef.current?.getMarkdown()).toBe(SOURCE);
diff --git a/packages/ui/components/MarkdownEditor.tsx b/packages/ui/components/MarkdownEditor.tsx
index 571edc542..804ebdf57 100644
--- a/packages/ui/components/MarkdownEditor.tsx
+++ b/packages/ui/components/MarkdownEditor.tsx
@@ -93,10 +93,12 @@ interface MarkdownEditorProps {
 export const MarkdownEditor: React.FC<MarkdownEditorProps> = ({ gridEnabled, mode, ...props }) => {
   const { resolvedMode } = useTheme();
   return (
-    <PackagedMarkdownEditor
-      {...props}
-      mode={mode ?? resolvedMode}
-      cardClassName={gridEnabled ? GRID_CARD_CLASSES : undefined}
-    />
+    <div data-pn-mobile-editable-surface="true" className="contents">
+      <PackagedMarkdownEditor
+        {...props}
+        mode={mode ?? resolvedMode}
+        cardClassName={gridEnabled ? GRID_CARD_CLASSES : undefined}
+      />
+    </div>
   );
 };
diff --git a/packages/ui/components/PlanHeaderMenu.tsx b/packages/ui/components/PlanHeaderMenu.tsx
index d054cf1c4..cf8135eb9 100644
--- a/packages/ui/components/PlanHeaderMenu.tsx
+++ b/packages/ui/components/PlanHeaderMenu.tsx
@@ -88,7 +88,7 @@ export const PlanHeaderMenu: React.FC<PlanHeaderMenuProps> = ({
       }
       renderTrigger={({ isOpen, toggleMenu }) => (
         <button
-          id={compactTouchLayout ? 'pn-compact-plan-options-trigger' : undefined}
+          id={compactTouchLayout ? 'pn-compact-plan-options-trigger' : 'pn-plan-options-trigger'}
           data-pn-touch-target={compactTouchLayout || undefined}
           data-pn-touch-target-icon={compactTouchLayout || undefined}
           onClick={() => {
diff --git a/packages/ui/components/PopoutDialog.mobile.test.tsx b/packages/ui/components/PopoutDialog.mobile.test.tsx
new file mode 100644
index 000000000..877f8af43
--- /dev/null
+++ b/packages/ui/components/PopoutDialog.mobile.test.tsx
@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { PopoutDialog } from './PopoutDialog';
+
+const hasDom = typeof document !== 'undefined';
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = null;
+  host?.remove();
+  host = null;
+  if (hasDom) document.body.replaceChildren();
+});
+
+describe('PopoutDialog visible viewport shell', () => {
+  test.skipIf(!hasDom)('centers editable popouts inside the observed viewport', async () => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+
+    await act(async () => {
+      root?.render(
+        <PopoutDialog open onClose={() => {}} title="Code file">
+          <textarea data-pn-mobile-editable defaultValue="draft" />
+        </PopoutDialog>,
+      );
+    });
+
+    const stage = document.querySelector<HTMLElement>('.pn-visible-viewport-overlay');
+    const popup = document.querySelector<HTMLElement>('[data-popout="true"]');
+    const close = document.querySelector<HTMLButtonElement>('button[aria-label="Close"]');
+
+    expect(stage?.className).toContain('pointer-events-none');
+    expect(popup?.className).toContain('pointer-events-auto');
+    expect(popup?.className).toContain('var(--pn-viewport-height,100vh)');
+    expect(close?.getAttribute('data-pn-touch-target')).toBe('true');
+    expect(close?.getAttribute('data-pn-touch-target-icon')).toBe('true');
+  });
+});
diff --git a/packages/ui/components/PopoutDialog.tsx b/packages/ui/components/PopoutDialog.tsx
index 8d97f8b61..0d7e51fac 100644
--- a/packages/ui/components/PopoutDialog.tsx
+++ b/packages/ui/components/PopoutDialog.tsx
@@ -82,28 +82,32 @@ export const PopoutDialog: React.FC<PopoutDialogProps> = ({
           onClick={handleBackdropClick}
           aria-hidden="true"
         />
-        <Dialog.Popup
-          className={`fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2 bg-background border border-border rounded-xl shadow-2xl flex flex-col overflow-hidden ${className ?? 'w-[calc(100vw-4rem)] max-w-[min(calc(100vw-4rem),1500px)] max-h-[calc(100vh-4rem)]'}`}
-          data-popout="true"
-          initialFocus={false}
-          {...dataAttributes}
-        >
-          <Dialog.Title className="sr-only">{title}</Dialog.Title>
-          <Dialog.Close
-            render={
-              <button
-                className="absolute top-3 right-3 z-20 p-1.5 rounded-md text-muted-foreground/70 hover:bg-muted hover:text-foreground transition-colors"
-                aria-label="Close"
-              />
-            }
+        <div className="pn-visible-viewport-overlay pointer-events-none z-50 flex items-center justify-center">
+          <Dialog.Popup
+            className={`pointer-events-auto relative z-50 flex flex-col overflow-hidden rounded-xl border border-border bg-background shadow-2xl ${className ?? 'w-[calc(var(--pn-viewport-width,100vw)-4rem)] max-w-[min(calc(var(--pn-viewport-width,100vw)-4rem),1500px)] max-h-[calc(var(--pn-viewport-height,100vh)-4rem)]'}`}
+            data-popout="true"
+            initialFocus={false}
+            {...dataAttributes}
           >
-            <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-              <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
-            </svg>
-          </Dialog.Close>
+            <Dialog.Title className="sr-only">{title}</Dialog.Title>
+            <Dialog.Close
+              render={
+                <button
+                  data-pn-touch-target
+                  data-pn-touch-target-icon
+                  className="absolute top-3 right-3 z-20 p-1.5 rounded-md text-muted-foreground/70 hover:bg-muted hover:text-foreground transition-colors"
+                  aria-label="Close"
+                />
+              }
+            >
+              <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+              </svg>
+            </Dialog.Close>
 
-          {children}
-        </Dialog.Popup>
+            {children}
+          </Dialog.Popup>
+        </div>
       </Dialog.Portal>
     </Dialog.Root>
   );
diff --git a/packages/ui/components/SearchableSelect.mobile.test.tsx b/packages/ui/components/SearchableSelect.mobile.test.tsx
new file mode 100644
index 000000000..ecc77a776
--- /dev/null
+++ b/packages/ui/components/SearchableSelect.mobile.test.tsx
@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { SearchableSelect } from './SearchableSelect';
+
+const hasDom = typeof document !== 'undefined';
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+let originalMatchMedia: typeof window.matchMedia | undefined;
+
+function pointerMatchMedia(coarse: boolean): typeof window.matchMedia {
+  return (query: string): MediaQueryList => ({
+    matches: coarse && query.includes('pointer: coarse'),
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => true,
+  });
+}
+
+async function mountPicker(coarse: boolean): Promise<HTMLButtonElement> {
+  originalMatchMedia = window.matchMedia;
+  window.matchMedia = pointerMatchMedia(coarse);
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  root = createRoot(host);
+  await act(async () => {
+    root?.render(
+      <SearchableSelect
+        items={[{ id: 'one', label: 'One' }]}
+        onSelect={() => {}}
+        filterFn={(item, query) => item.label.toLowerCase().includes(query.toLowerCase())}
+        renderItem={(item) => item.label}
+        renderTrigger={() => <button type="button">Choose item</button>}
+      />,
+    );
+  });
+  const trigger = host.querySelector<HTMLButtonElement>('button');
+  if (!trigger) throw new Error('SearchableSelect trigger did not render');
+  trigger.focus();
+  await act(async () => trigger.click());
+  await act(async () => new Promise((resolve) => setTimeout(resolve, 0)));
+  return trigger;
+}
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = null;
+  host?.remove();
+  host = null;
+  if (hasDom) {
+    document.body.replaceChildren();
+    if (originalMatchMedia) window.matchMedia = originalMatchMedia;
+  }
+});
+
+describe('SearchableSelect mobile focus policy', () => {
+  test.skipIf(!hasDom)('opens passive coarse-pointer pickers without focusing the search field', async () => {
+    const trigger = await mountPicker(true);
+    const input = document.querySelector<HTMLInputElement>('[data-pn-mobile-editable]');
+
+    expect(input).not.toBeNull();
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  test.skipIf(!hasDom)('preserves immediate keyboard search on fine pointers', async () => {
+    await mountPicker(false);
+    const input = document.querySelector<HTMLInputElement>('[data-pn-mobile-editable]');
+
+    expect(input).not.toBeNull();
+    expect(document.activeElement).toBe(input);
+  });
+});
diff --git a/packages/ui/components/SearchableSelect.tsx b/packages/ui/components/SearchableSelect.tsx
index 390196190..97a4c1700 100644
--- a/packages/ui/components/SearchableSelect.tsx
+++ b/packages/ui/components/SearchableSelect.tsx
@@ -1,5 +1,6 @@
 import React, { useState, useMemo, useRef, useCallback, type ReactElement, type ReactNode } from 'react';
 import { Popover, PopoverTrigger, PopoverContent } from './Popover';
+import { shouldAutoFocusPassiveSearch } from '../hooks/useViewportEnvironment';
 
 interface SearchableSelectProps<T extends { id: string }> {
   items: T[];
@@ -87,9 +88,10 @@ export function SearchableSelect<T extends { id: string }>({
     <Popover open={open} onOpenChange={handleOpenChange}>
       <PopoverTrigger render={renderTrigger({ open })} />
       <PopoverContent
+        data-pn-secondary-input-picker
         align={align}
         className={`${width} p-0`}
-        initialFocus={inputRef}
+        initialFocus={shouldAutoFocusPassiveSearch() ? inputRef : false}
       >
         {/* Search row */}
         <div className="flex items-center gap-2 border-b border-border/50 px-3 py-2">
diff --git a/packages/ui/components/blocks/TablePopout.tsx b/packages/ui/components/blocks/TablePopout.tsx
index 5bb4936b9..f4623be97 100644
--- a/packages/ui/components/blocks/TablePopout.tsx
+++ b/packages/ui/components/blocks/TablePopout.tsx
@@ -146,6 +146,7 @@ const TablePopoutImpl: React.FC<TablePopoutProps> = ({
             <path strokeLinecap="round" strokeLinejoin="round" d="M21 21l-4.35-4.35M10 18a8 8 0 100-16 8 8 0 000 16z" />
           </svg>
           <input
+            data-pn-mobile-editable
             type="text"
             value={globalFilter}
             onChange={(e) => setGlobalFilter(e.target.value)}
diff --git a/packages/ui/components/core/textarea.tsx b/packages/ui/components/core/textarea.tsx
index 6da7953a9..62331a377 100644
--- a/packages/ui/components/core/textarea.tsx
+++ b/packages/ui/components/core/textarea.tsx
@@ -14,6 +14,7 @@ export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(({
   ...props
 }, ref) => (
   <textarea
+    data-pn-mobile-editable
     ref={ref}
     className={cx(
       'min-h-24 w-full resize-none rounded-md border border-border bg-background px-3 py-2 text-sm leading-6 text-foreground outline-none transition-colors placeholder:text-muted-foreground/70 focus:border-primary/60 focus:ring-2 focus:ring-primary/15',
diff --git a/packages/ui/components/goal-setup/GoalSetupSurface.tsx b/packages/ui/components/goal-setup/GoalSetupSurface.tsx
index 614b97512..f38e7ec4b 100644
--- a/packages/ui/components/goal-setup/GoalSetupSurface.tsx
+++ b/packages/ui/components/goal-setup/GoalSetupSurface.tsx
@@ -745,6 +745,7 @@ const QuestionAnswerControls: React.FC<{
                 {answer.customAnswer.trim() ? <Check className="h-2 w-2" strokeWidth={3} /> : <Plus className="h-2 w-2" strokeWidth={3} />}
               </span>
               <input
+                data-pn-mobile-editable
                 value={answer.customAnswer}
                 onChange={(event) => updateCustomOption(event.target.value)}
                 placeholder="Other…"
diff --git a/packages/ui/components/sidebar/FileBrowser.tsx b/packages/ui/components/sidebar/FileBrowser.tsx
index 615ee962e..7ec522655 100644
--- a/packages/ui/components/sidebar/FileBrowser.tsx
+++ b/packages/ui/components/sidebar/FileBrowser.tsx
@@ -543,6 +543,7 @@ export const FileBrowser: React.FC<FileBrowserProps> = ({
           >
             <Search size={12} className="shrink-0 text-muted-foreground/55" aria-hidden="true" />
             <input
+              data-pn-mobile-editable
               ref={inputRef}
               type="search"
               value={filterQuery}
diff --git a/packages/ui/components/ui/mobile-foundation.test.tsx b/packages/ui/components/ui/mobile-foundation.test.tsx
index bb8ba0a1f..c4961e47f 100644
--- a/packages/ui/components/ui/mobile-foundation.test.tsx
+++ b/packages/ui/components/ui/mobile-foundation.test.tsx
@@ -7,6 +7,8 @@ import { renderToStaticMarkup } from 'react-dom/server';
 import { Button as LegacyButton } from '../core/button';
 import { Button } from './button';
 import { Dialog, DialogContent, DialogDescription, DialogTitle } from './dialog';
+import { Textarea as LegacyTextarea } from '../core/textarea';
+import { Textarea } from './textarea';
 
 const hasDom = typeof document !== 'undefined';
 
@@ -39,6 +41,20 @@ describe('shared mobile control foundation', () => {
     expect(theme).toContain('touch-action: manipulation');
     expect(theme).not.toContain('@media (any-pointer: coarse)');
     expect(theme).toContain('@media (prefers-reduced-motion: reduce)');
+    expect(theme).toContain("[data-pn-mobile-editable-surface] [contenteditable='true']");
+    expect(theme).toContain('[data-pn-secondary-input-dialog]');
+    expect(theme).toContain('input[data-pn-mobile-editable]');
+    expect(theme).toContain('[data-pn-secondary-input-picker]');
+  });
+
+  test('marks canonical multiline editors for the compact 16px floor', () => {
+    const current = renderToStaticMarkup(<Textarea placeholder="Current" />);
+    const legacy = renderToStaticMarkup(<LegacyTextarea placeholder="Legacy" />);
+
+    expect(current).toContain('data-pn-mobile-editable="true"');
+    expect(legacy).toContain('data-pn-mobile-editable="true"');
+    expect(current).toContain('md:text-sm');
+    expect(legacy).toContain('text-sm');
   });
 
   test('marks canonical buttons without changing their visual size classes', () => {
diff --git a/packages/ui/components/ui/textarea.tsx b/packages/ui/components/ui/textarea.tsx
index a40263cee..c48c5378f 100644
--- a/packages/ui/components/ui/textarea.tsx
+++ b/packages/ui/components/ui/textarea.tsx
@@ -11,6 +11,7 @@ function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
   return (
     <textarea
       data-slot="textarea"
+      data-pn-mobile-editable
       className={cn(
         "flex field-sizing-content min-h-16 w-full rounded-md border border-input bg-background px-3 py-2 text-base shadow-xs outline-none transition-[color,box-shadow] placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
         "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
diff --git a/packages/ui/hooks/useModalFocusLifecycle.test.tsx b/packages/ui/hooks/useModalFocusLifecycle.test.tsx
new file mode 100644
index 000000000..375789ae3
--- /dev/null
+++ b/packages/ui/hooks/useModalFocusLifecycle.test.tsx
@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import React, { act, useState } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { useModalFocusLifecycle } from './useModalFocusLifecycle';
+
+const hasDom = typeof document !== 'undefined';
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = null;
+  host?.remove();
+  host = null;
+  if (hasDom) document.body.replaceChildren();
+});
+
+describe('useModalFocusLifecycle', () => {
+  test.skipIf(!hasDom)('can restore focus without overriding a surface-specific Escape action', async () => {
+    let closeCount = 0;
+
+    function Harness() {
+      const [open, setOpen] = useState(false);
+      useModalFocusLifecycle(
+        open,
+        () => {
+          closeCount += 1;
+          setOpen(false);
+        },
+        { dismissOnEscape: false },
+      );
+      return (
+        <>
+          <button type="button" onClick={() => setOpen(true)}>Open</button>
+          {open && <button type="button" onClick={() => setOpen(false)}>Accept</button>}
+        </>
+      );
+    }
+
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+    await act(async () => root?.render(<Harness />));
+
+    const opener = host.querySelector<HTMLButtonElement>('button');
+    opener?.focus();
+    await act(async () => opener?.click());
+    await act(async () => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    });
+
+    expect(closeCount).toBe(0);
+    const accept = Array.from(host.querySelectorAll<HTMLButtonElement>('button'))
+      .find((button) => button.textContent === 'Accept');
+    await act(async () => accept?.click());
+    await new Promise<void>((resolve) => {
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+
+    expect(document.activeElement).toBe(opener);
+  });
+});
diff --git a/packages/ui/hooks/useModalFocusLifecycle.ts b/packages/ui/hooks/useModalFocusLifecycle.ts
new file mode 100644
index 000000000..03e455ea0
--- /dev/null
+++ b/packages/ui/hooks/useModalFocusLifecycle.ts
@@ -0,0 +1,56 @@
+import { useEffect, useRef } from 'react';
+
+interface ModalFocusLifecycleOptions {
+  dismissOnEscape?: boolean;
+  fallbackFocusId?: string;
+}
+
+/**
+ * Gives legacy custom modal shells the minimum keyboard lifecycle provided by
+ * the shared dialog primitive: Escape dismissal and focus restoration. New
+ * dialogs should still prefer the shared Base UI wrapper.
+ */
+export function useModalFocusLifecycle(
+  active: boolean,
+  onClose: () => void,
+  {
+    dismissOnEscape = true,
+    fallbackFocusId,
+  }: ModalFocusLifecycleOptions = {},
+): void {
+  const onCloseRef = useRef(onClose);
+  const restoreFocusRef = useRef<HTMLElement | null>(null);
+  const fallbackFocusIdRef = useRef(fallbackFocusId);
+  const dismissOnEscapeRef = useRef(dismissOnEscape);
+  onCloseRef.current = onClose;
+  fallbackFocusIdRef.current = fallbackFocusId;
+  dismissOnEscapeRef.current = dismissOnEscape;
+  if (!active) {
+    restoreFocusRef.current = null;
+  } else if (restoreFocusRef.current === null && typeof document !== 'undefined') {
+    const activeElement = document.activeElement;
+    restoreFocusRef.current = activeElement instanceof HTMLElement ? activeElement : null;
+  }
+
+  useEffect(() => {
+    if (!active) return;
+    const previouslyFocused = restoreFocusRef.current;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (!dismissOnEscapeRef.current || event.key !== 'Escape' || event.defaultPrevented) return;
+      event.preventDefault();
+      onCloseRef.current();
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      const fallbackId = fallbackFocusIdRef.current;
+      const fallback = fallbackId ? document.getElementById(fallbackId) : null;
+      const focusTarget = fallback ?? (previouslyFocused?.isConnected ? previouslyFocused : null);
+      if (!focusTarget) return;
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => focusTarget.focus({ preventScroll: true }));
+      });
+    };
+  }, [active]);
+}
diff --git a/packages/ui/hooks/useViewportEnvironment.test.tsx b/packages/ui/hooks/useViewportEnvironment.test.tsx
index 63a0f5565..569d29600 100644
--- a/packages/ui/hooks/useViewportEnvironment.test.tsx
+++ b/packages/ui/hooks/useViewportEnvironment.test.tsx
@@ -4,6 +4,7 @@ import { createRoot, type Root } from 'react-dom/client';
 import {
   calculateVisibleViewportBounds,
   calculateViewportEnvironment,
+  shouldAutoFocusPassiveSearch,
   shouldUseExpandedComposer,
   useViewportEnvironment,
 } from './useViewportEnvironment';
@@ -17,6 +18,26 @@ const VIEWPORT_PROPERTIES = [
   '--pn-keyboard-inset',
 ] as const;
 
+function pointerMatchMedia(coarse: boolean): (query: string) => MediaQueryList {
+  return (query: string): MediaQueryList => ({
+    matches: coarse && query.includes('pointer: coarse'),
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => true,
+  });
+}
+
+describe('passive search focus policy', () => {
+  test('preserves keyboard-first desktop search without summoning a touch keyboard', () => {
+    expect(shouldAutoFocusPassiveSearch({ matchMedia: pointerMatchMedia(false) })).toBe(true);
+    expect(shouldAutoFocusPassiveSearch({ matchMedia: pointerMatchMedia(true) })).toBe(false);
+  });
+});
+
 let roots: Root[] = [];
 let hosts: HTMLElement[] = [];
 
diff --git a/packages/ui/hooks/useViewportEnvironment.ts b/packages/ui/hooks/useViewportEnvironment.ts
index c68595044..3146d2293 100644
--- a/packages/ui/hooks/useViewportEnvironment.ts
+++ b/packages/ui/hooks/useViewportEnvironment.ts
@@ -184,12 +184,19 @@ export function shouldUseExpandedComposer({
 }
 
 /** Returns whether the device's primary pointing input is coarse. */
-export function hasPrimaryCoarsePointer(targetWindow?: Window): boolean {
+export function hasPrimaryCoarsePointer(targetWindow?: Pick<Window, 'matchMedia'>): boolean {
   const resolvedWindow = targetWindow ?? (typeof window === 'undefined' ? undefined : window);
   if (!resolvedWindow?.matchMedia) return false;
   return resolvedWindow.matchMedia('(pointer: coarse)').matches;
 }
 
+/** Passive searchable pickers keep their opener focused on touch devices. */
+export function shouldAutoFocusPassiveSearch(
+  targetWindow?: Pick<Window, 'matchMedia'>,
+): boolean {
+  return !hasPrimaryCoarsePointer(targetWindow);
+}
+
 function readViewportEnvironment(targetWindow: Window): ViewportEnvironment {
   const visualViewport = targetWindow.visualViewport;
   return calculateViewportEnvironment({
diff --git a/packages/ui/theme.css b/packages/ui/theme.css
index 023f4974a..c733aa304 100644
--- a/packages/ui/theme.css
+++ b/packages/ui/theme.css
@@ -877,7 +877,8 @@ body:has([data-pn-document-scroll="true"]) > #root {
  * metrically identical to the transparent textarea above it. */
 @media (pointer: coarse), (max-width: 639px) {
   [data-pn-mobile-editable],
-  [data-pn-mobile-editable-mirror] {
+  [data-pn-mobile-editable-mirror],
+  [data-pn-mobile-editable-surface] [contenteditable='true'] {
     font-size: 1rem !important;
   }
 }
@@ -892,11 +893,69 @@ html:has([data-pn-compact-touch-layout='true']) [data-pn-touch-target] {
   touch-action: manipulation;
 }
 
+html:has([data-pn-compact-touch-layout='true'])
+  input[data-pn-mobile-editable] {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-secondary-input-picker]
+  button {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
 html:has([data-pn-compact-touch-layout='true'])
   [data-pn-touch-target][data-pn-touch-target-icon] {
   min-inline-size: var(--pn-touch-target);
 }
 
+/* Legacy input dialogs predate the shared Button primitive. Their wrapper is
+ * the migration seam so every nested action becomes a reliable touch target
+ * without changing the dense desktop controls. */
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-secondary-input-dialog]
+  button {
+  min-block-size: var(--pn-touch-target);
+  touch-action: manipulation;
+}
+
+html:has([data-pn-compact-touch-layout='true'])
+  [data-pn-secondary-input-dialog]
+  button[aria-label] {
+  min-inline-size: var(--pn-touch-target);
+}
+
+.pn-suggestion-dialog {
+  width: 60rem;
+  max-width: 100%;
+  max-height: 100%;
+}
+
+@media (pointer: coarse), (max-width: 639px), (max-width: 900px) and (max-height: 419px) {
+  .pn-suggestion-dialog {
+    height: 100%;
+  }
+
+  .pn-suggestion-panes {
+    flex-direction: column;
+  }
+
+  .pn-suggestion-original {
+    border-right-width: 0 !important;
+    border-bottom-width: 1px;
+  }
+
+  .pn-suggestion-layout-toggle {
+    display: none;
+  }
+
+  .suggested-code-input {
+    min-height: 0 !important;
+  }
+}
+
 html:has([data-pn-compact-touch-layout='true'])
   [data-pn-compact-diff-options]
   button {

From b79ef404d404271e63b777166cded037ebae679a Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Sun, 23 Aug 2026 14:20:21 -0700
Subject: [PATCH 2/2] chore: sync guide viewer manifest

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

diff --git a/packages/core/guide-viewer-manifest.ts b/packages/core/guide-viewer-manifest.ts
index a3446bd79..005aad9d4 100644
--- a/packages/core/guide-viewer-manifest.ts
+++ b/packages/core/guide-viewer-manifest.ts
@@ -5,10 +5,10 @@
 import type { GuideViewerAssets } from "./guide-format";
 
 export const GUIDE_VIEWER_MANIFEST: Omit<GuideViewerAssets, "baseUrl"> = {
-  js: "viewer.CTfggrYt.js",
-  css: "viewer.BdruF6Mj.css",
-  jsIntegrity: "sha384-It85Hkx0/d1Xme4SJjt3shHybLPGucRF/OODzE84mbOmGH8fK66eFNzgFRXe2W4Z",
-  cssIntegrity: "sha384-9i0z0HV8a5Hr0SAQt0+pUfQE96MTbGaCWtZlSzhk+HKIHXsqrGi16HQA4mlEWRvx",
+  js: "viewer.DsVT7zHg.js",
+  css: "viewer.BZrAP09o.css",
+  jsIntegrity: "sha384-GqsJAyczOLBwgFdmWfMxhi3P95GhDLgzDfgQOvoX7A7SH/25lxgU3wTUQMmnzzvd",
+  cssIntegrity: "sha384-qqI5FLKY4BfdFBlERBab5UhQOeP12/PBvKklCqJX+1P3WrMnSA1rORxnYpdqHBRp",
   langs: {
     "astro": "chunks/astro.BykyiR6i.js",
     "c": "chunks/c.BIGW1oBm.js",