fix(ui): harden compact touch behavior

Author: backnotprop

packages/editor/App.tsx

@@ -57,11 +57,8 @@ import {
   ScrollViewportProvider,
 } from '@plannotator/ui/hooks/useScrollViewport';
 import { useOverlayViewport } from '@plannotator/ui/hooks/useOverlayViewport';
-import { useIsMobile } from '@plannotator/ui/hooks/useIsMobile';
-import {
-  hasCoarsePointer,
-  useViewportEnvironment,
-} from '@plannotator/ui/hooks/useViewportEnvironment';
+import { useCompactTouchLayout, useIsMobile } from '@plannotator/ui/hooks/useIsMobile';
+import { useViewportEnvironment } from '@plannotator/ui/hooks/useViewportEnvironment';
 import {
   getPermissionModeSettings,
   needsPermissionModeSetup,
@@ -523,8 +520,7 @@ const App: React.FC = () => {
   });
   const [showLookAndFeelAnnouncement, setShowLookAndFeelAnnouncement] = useState(needsLookAndFeelAnnouncement);
   const isMobile = useIsMobile();
-  const isMobilePageScrollWidth = useIsMobile(1025);
-  const usesDocumentScroll = isMobilePageScrollWidth && hasCoarsePointer();
+  const usesDocumentScroll = useCompactTouchLayout();
 
   const viewerRef = useRef<ViewerHandle>(null);
   // Desktop uses the main document element as its native scroll viewport.
@@ -4255,6 +4251,7 @@ const App: React.FC = () => {
       <div
         data-print-region="root"
         data-pn-browser-canvas={browserCanvas}
+        data-pn-compact-touch-layout={usesDocumentScroll ? 'true' : undefined}
         data-pn-document-scroll={usesDocumentScroll ? 'true' : undefined}
         className={`pn-app-viewport flex flex-col ${usesDocumentScroll ? 'overflow-visible' : 'overflow-hidden'} ${browserCanvas === 'card' ? 'bg-card' : 'bg-background'}`}
       >

packages/review-editor/components/AnnotationToolbar.tsx

@@ -10,7 +10,7 @@ import type { ConventionalLabel, ConventionalDecoration } from '@plannotator/ui/
 import type { AIChatEntry } from '../hooks/useAIChat';
 import { useDraggable } from '@plannotator/ui/hooks/useDraggable';
 import {
-  hasCoarsePointer,
+  hasPrimaryCoarsePointer,
   useVisibleViewportBounds,
 } from '@plannotator/ui/hooks/useViewportEnvironment';
 
@@ -79,7 +79,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
   onViewAIResponse,
   aiHistoryMessages = [],
 }) => {
-  const coarsePointer = hasCoarsePointer();
+  const coarsePointer = hasPrimaryCoarsePointer();
   const visibleBounds = useVisibleViewportBounds(coarsePointer ? 16 : 0);
   const horizontalInset = coarsePointer ? Math.min(160, visibleBounds.width / 2) : 150;
   const suggestedCodeRef = useRef<HTMLTextAreaElement>(null);
@@ -206,7 +206,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
             value={commentText}
             onChange={(e) => setCommentText(e.target.value)}
             placeholder="Leave feedback..."
-            className="w-full min-h-[4.5rem] max-h-[calc(var(--pn-viewport-height,100dvh)-16rem)] px-3 py-2 bg-muted rounded-lg text-xs leading-6 resize-y border-0 focus:outline-none focus:ring-1 focus:ring-primary/50 placeholder:text-muted-foreground"
+            className="w-full min-h-[4.5rem] max-h-[calc(var(--pn-viewport-height,100vh)-16rem)] px-3 py-2 bg-muted rounded-lg text-xs leading-6 resize-y border-0 focus:outline-none focus:ring-1 focus:ring-primary/50 placeholder:text-muted-foreground"
             rows={3}
             autoFocus={!coarsePointer}
             onKeyDown={(e) => {

packages/review-editor/hooks/useAnnotationToolbar.ts

@@ -2,7 +2,7 @@ import { useState, useCallback, useRef, useEffect } from 'react';
 import { CodeAnnotation, SelectedLineRange, CodeAnnotationType, TokenAnnotationMeta, ConventionalLabel, ConventionalDecoration } from '@plannotator/ui/types';
 import { useDismissOnOutsideAndEscape } from '@plannotator/ui/hooks/useDismissOnOutsideAndEscape';
 import {
-  hasCoarsePointer,
+  hasPrimaryCoarsePointer,
   shouldUseExpandedComposer,
   useVisibleViewportBounds,
 } from '@plannotator/ui/hooks/useViewportEnvironment';
@@ -62,7 +62,7 @@ export function useAnnotationToolbar({ patch, filePath, isFocused, onLineSelecti
   const visibleBounds = useVisibleViewportBounds(16);
   const expandedComposerRequired = shouldUseExpandedComposer({
     bounds: visibleBounds,
-    coarsePointer: hasCoarsePointer(),
+    coarsePointer: hasPrimaryCoarsePointer(),
   });
   const toolbarRef = useRef<HTMLDivElement>(null);
   const lastMousePosition = useRef<{ x: number; y: number }>({ x: 0, y: 0 });

packages/ui/components/CommentPopover.mobile.test.tsx

@@ -153,4 +153,51 @@ describe('CommentPopover mobile composition', () => {
     expect(document.querySelector<HTMLTextAreaElement>('[data-pn-mobile-editable]')?.value)
       .toBe('Keep this draft');
   });
+
+  test.skipIf(!hasDom)('keeps focus on a newly tapped outside target', async () => {
+    // SAFETY: The test double implements the MediaQueryList surface consumed by the component.
+    window.matchMedia = ((query: string): MediaQueryList => ({
+      ...coarseMatchMedia(query),
+      matches: false,
+    })) as typeof window.matchMedia;
+
+    function Harness() {
+      const triggerRef = useRef<HTMLButtonElement>(null);
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <button ref={triggerRef} onClick={() => setOpen(true)}>Open</button>
+          <button>Next target</button>
+          {open && (
+            <CommentPopover
+              anchorEl={triggerRef.current ?? undefined}
+              anchorRect={new DOMRect(40, 40, 80, 24)}
+              contextText="selected text"
+              isGlobal={false}
+              onSubmit={() => {}}
+              onClose={() => setOpen(false)}
+            />
+          )}
+        </>
+      );
+    }
+
+    await mount(<Harness />);
+    const buttons = Array.from(document.querySelectorAll<HTMLButtonElement>('button'));
+    const trigger = buttons.find((button) => button.textContent === 'Open');
+    const nextTarget = buttons.find((button) => button.textContent === 'Next target');
+    expect(trigger).not.toBeUndefined();
+    expect(nextTarget).not.toBeUndefined();
+
+    await act(async () => trigger?.click());
+    await act(async () => {
+      nextTarget?.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
+      nextTarget?.focus();
+      nextTarget?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    await act(async () => new Promise<void>(resolve => requestAnimationFrame(() => resolve())));
+
+    expect(document.querySelector('[data-comment-popover]')).toBeNull();
+    expect(document.activeElement).toBe(nextTarget);
+  });
 });

packages/ui/components/CommentPopover.tsx

@@ -10,7 +10,7 @@ import { useSkillReferenceAutocomplete } from '../hooks/useSkillReferenceAutocom
 import { HumanOnlySkillNotice, SkillReferenceMenu } from './SkillReferenceMenu';
 import type { SkillReferenceToken } from '../utils/skillReferences';
 import {
-  hasCoarsePointer,
+  hasPrimaryCoarsePointer,
   shouldUseExpandedComposer,
   useVisibleViewportBounds,
   type VisibleViewportBounds,
@@ -165,7 +165,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   yieldState,
 }) => {
   const visibleBounds = useVisibleViewportBounds(16);
-  const coarsePointer = hasCoarsePointer();
+  const coarsePointer = hasPrimaryCoarsePointer();
   const prefersExpandedComposer = shouldUseExpandedComposer({
     bounds: visibleBounds,
     coarsePointer,
@@ -293,17 +293,20 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
     });
   }, []);
 
-  const handleClose = useCallback(() => {
-    if (draftKey) {
-      if (hasUnsavedCommentContent(text, allowImages ? images : [])) {
-        draftStore.set(draftKey, { text, images: allowImages ? images : [] });
-      } else {
-        draftStore.delete(draftKey);
+  const handleClose = useCallback(
+    (focusDisposition: 'restore-opener' | 'preserve-pointer-target' = 'restore-opener') => {
+      if (draftKey) {
+        if (hasUnsavedCommentContent(text, allowImages ? images : [])) {
+          draftStore.set(draftKey, { text, images: allowImages ? images : [] });
+        } else {
+          draftStore.delete(draftKey);
+        }
       }
-    }
-    onClose();
-    restoreOpeningFocus();
-  }, [allowImages, draftKey, images, onClose, restoreOpeningFocus, text]);
+      onClose();
+      if (focusDisposition === 'restore-opener') restoreOpeningFocus();
+    },
+    [allowImages, draftKey, images, onClose, restoreOpeningFocus, text],
+  );
 
   // Click-outside for popover mode
   useEffect(() => {
@@ -322,7 +325,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
       // Preserve the existing draft so the following Shift-click can extend
       // it instead of silently replacing it with a new one.
       if (shiftSelectionActive && e.shiftKey) return;
-      handleClose();
+      handleClose('preserve-pointer-target');
     };
 
     document.addEventListener('pointerdown', handlePointerDown, true);
@@ -512,7 +515,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
           type="button"
           aria-label="Dismiss comment"
           className="absolute inset-0 bg-background/80 backdrop-blur-sm"
-          onClick={handleClose}
+          onClick={() => handleClose()}
         />
 
         {/* Dialog card */}
@@ -561,7 +564,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
                 </button>
               )}
               <button
-                onClick={handleClose}
+                onClick={() => handleClose()}
                 className="p-1 rounded hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
                 title="Close"
               >
@@ -706,7 +709,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
             <ExpandIcon />
           </button>
           <button
-            onClick={handleClose}
+            onClick={() => handleClose()}
             className="p-1 rounded hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
             title="Close"
           >

packages/ui/hooks/useIsMobile.test.tsx

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import {
+  COMPACT_TOUCH_LAYOUT_MEDIA_QUERY,
+  useCompactTouchLayout,
+} from './useIsMobile';
+
+const hasDom = typeof document !== 'undefined';
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+let originalMatchMedia: typeof window.matchMedia | undefined;
+
+function Harness() {
+  const compact = useCompactTouchLayout();
+  return <output data-compact={compact ? 'true' : 'false'} />;
+}
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  root = null;
+  host?.remove();
+  host = null;
+  if (hasDom && originalMatchMedia) window.matchMedia = originalMatchMedia;
+  originalMatchMedia = undefined;
+});
+
+describe('useCompactTouchLayout', () => {
+  test('uses compact width and the primary coarse pointer', () => {
+    expect(COMPACT_TOUCH_LAYOUT_MEDIA_QUERY)
+      .toBe('(max-width: 1024px) and (pointer: coarse)');
+    expect(COMPACT_TOUCH_LAYOUT_MEDIA_QUERY).not.toContain('any-pointer');
+  });
+
+  test.skipIf(!hasDom)('follows media changes and removes its listener', async () => {
+    originalMatchMedia = window.matchMedia;
+    let matches = false;
+    const listeners = new Set<(event: MediaQueryListEvent) => void>();
+
+    // SAFETY: The test double implements the MediaQueryList surface consumed by the hook.
+    window.matchMedia = ((query: string): MediaQueryList => ({
+      matches,
+      media: query,
+      onchange: null,
+      addEventListener: (_type, listener) => listeners.add(listener),
+      removeEventListener: (_type, listener) => listeners.delete(listener),
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => true,
+    })) as typeof window.matchMedia;
+
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    root = createRoot(host);
+    await act(async () => root?.render(<Harness />));
+
+    expect(document.querySelector('output')?.getAttribute('data-compact')).toBe('false');
+    expect(listeners.size).toBe(1);
+
+    matches = true;
+    await act(async () => {
+      // SAFETY: The hook reads only `matches` from this synthetic media event.
+      for (const listener of listeners) listener({ matches } as MediaQueryListEvent);
+    });
+    expect(document.querySelector('output')?.getAttribute('data-compact')).toBe('true');
+
+    await act(async () => root?.unmount());
+    root = null;
+    expect(listeners.size).toBe(0);
+  });
+});

packages/ui/hooks/useIsMobile.ts

@@ -1,5 +1,17 @@
 import { useState, useEffect } from 'react';
 
+/** Maximum CSS viewport width that can enter Plannotator's compact touch shell. */
+export const COMPACT_TOUCH_LAYOUT_MAX_WIDTH = 1024;
+
+/**
+ * Canonical media query for the compact application shell.
+ *
+ * The primary pointer is intentional: `any-pointer: coarse` also matches
+ * touchscreen laptops whose primary mouse or trackpad needs the desktop shell.
+ */
+export const COMPACT_TOUCH_LAYOUT_MEDIA_QUERY =
+  `(max-width: ${COMPACT_TOUCH_LAYOUT_MAX_WIDTH}px) and (pointer: coarse)`;
+
 export function useIsMobile(breakpoint = 768): boolean {
   const [isMobile, setIsMobile] = useState(
     () => typeof window !== 'undefined' ? window.innerWidth < breakpoint : false
@@ -15,3 +27,28 @@ export function useIsMobile(breakpoint = 768): boolean {
 
   return isMobile;
 }
+
+/**
+ * Reports whether the current viewport needs Plannotator's compact touch shell.
+ * Plan and Code Review must share this decision so responsive chrome and scroll
+ * ownership cannot diverge on hybrid devices.
+ */
+export function useCompactTouchLayout(): boolean {
+  const [isCompactTouchLayout, setIsCompactTouchLayout] = useState(
+    () => typeof window !== 'undefined'
+      && window.matchMedia(COMPACT_TOUCH_LAYOUT_MEDIA_QUERY).matches,
+  );
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia(COMPACT_TOUCH_LAYOUT_MEDIA_QUERY);
+    const onChange = (event: MediaQueryListEvent) => {
+      setIsCompactTouchLayout(event.matches);
+    };
+
+    mediaQuery.addEventListener('change', onChange);
+    setIsCompactTouchLayout(mediaQuery.matches);
+    return () => mediaQuery.removeEventListener('change', onChange);
+  }, []);
+
+  return isCompactTouchLayout;
+}

packages/ui/hooks/useViewportEnvironment.ts

@@ -183,11 +183,11 @@ export function shouldUseExpandedComposer({
   return coarsePointer || bounds.width < 640 || bounds.height < 420;
 }
 
-export function hasCoarsePointer(targetWindow?: Window): boolean {
+/** Returns whether the device's primary pointing input is coarse. */
+export function hasPrimaryCoarsePointer(targetWindow?: Window): boolean {
   const resolvedWindow = targetWindow ?? (typeof window === 'undefined' ? undefined : window);
   if (!resolvedWindow?.matchMedia) return false;
-  return resolvedWindow.matchMedia('(any-pointer: coarse)').matches
-    || resolvedWindow.matchMedia('(pointer: coarse)').matches;
+  return resolvedWindow.matchMedia('(pointer: coarse)').matches;
 }
 
 function readViewportEnvironment(targetWindow: Window): ViewportEnvironment {

packages/ui/theme.css

@@ -745,6 +745,7 @@ body:has([data-pn-document-scroll="true"]) > #root {
 
 .pn-app-viewport[data-pn-document-scroll="true"] {
   height: auto;
+  min-height: 100vh;
   min-height: 100dvh;
 }
 
@@ -790,7 +791,7 @@ body:has([data-pn-document-scroll="true"]) > #root {
   left: var(--pn-viewport-offset-left, 0px);
   box-sizing: border-box;
   width: var(--pn-viewport-width, 100vw);
-  height: var(--pn-viewport-height, 100dvh);
+  height: var(--pn-viewport-height, 100vh);
   padding-top: max(1rem, var(--pn-safe-top));
   padding-right: max(1rem, var(--pn-safe-right));
   padding-bottom: max(1rem, var(--pn-safe-bottom));
@@ -802,6 +803,7 @@ body:has([data-pn-document-scroll="true"]) > #root {
  * strand the footer below an ornamental desktop margin. */
 .pn-responsive-composer-dialog {
   width: 100%;
+  height: min(36rem, 85vh);
   height: min(36rem, 85dvh);
   max-width: 42rem;
   max-height: 100%;