@plannotator/ui 0.29.1 → 0.31.0

package/components/sidebar/SidebarContainer.tsx

@@ -20,6 +20,9 @@ import { OverlayScrollArea } from "../OverlayScrollArea";
 import { ReviewAgentsIcon } from "../ReviewAgentsIcon";
 
 interface SidebarContainerProps {
+  /** Desktop preserves the incumbent sticky rail. Compact Plan uses the same
+   * content as a safe, visible-viewport-bounded foreground surface. */
+  presentation?: "desktop" | "overlay";
   activeTab: SidebarTab;
   onTabChange: (tab: SidebarTab) => void;
   onClose: () => void;
@@ -29,6 +32,7 @@ interface SidebarContainerProps {
   isAgentTerminalRunning?: boolean;
   onToggleAgentTerminal?: () => void;
   // TOC props
+  showContentsTab?: boolean;
   blocks: Block[];
   annotations: Annotation[];
   activeSection: string | null;
@@ -45,6 +49,8 @@ interface SidebarContainerProps {
   onFilesSelectFile?: (absolutePath: string, dirPath: string) => void;
   onFilesFetchAll?: () => void;
   onFilesRetryVaultDir?: (vaultPath: string) => void;
+  /** Compact-only file activation feedback; desktop does not pass this. */
+  pendingFileLabel?: string | null;
   // Version Browser props
   showVersionsTab?: boolean;
   versionInfo: VersionInfo | null;
@@ -74,6 +80,7 @@ interface SidebarContainerProps {
 }
 
 export const SidebarContainer: React.FC<SidebarContainerProps> = ({
+  presentation = "desktop",
   activeTab,
   onTabChange,
   onClose,
@@ -82,6 +89,7 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
   isAgentTerminalOpen,
   isAgentTerminalRunning,
   onToggleAgentTerminal,
+  showContentsTab = true,
   blocks,
   annotations,
   activeSection,
@@ -97,6 +105,7 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
   onFilesSelectFile,
   onFilesFetchAll,
   onFilesRetryVaultDir,
+  pendingFileLabel,
   showVersionsTab,
   versionInfo,
   versions,
@@ -121,14 +130,87 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
   onSelectMessage,
   messageAnnotationCounts,
 }) => {
+  const compact = presentation === "overlay";
+  const closeButtonRef = React.useRef<HTMLButtonElement>(null);
+
+  React.useEffect(() => {
+    if (compact) closeButtonRef.current?.focus({ preventScroll: true });
+  }, [compact]);
+
+  const handleCompactKeyDown = (event: React.KeyboardEvent<HTMLElement>) => {
+    if (!compact) return;
+    if (event.key === "Escape") {
+      event.preventDefault();
+      event.stopPropagation();
+      onClose();
+      return;
+    }
+    if (event.key !== "Tab") return;
+    const focusable = Array.from(
+      event.currentTarget.querySelectorAll<HTMLElement>(
+        'button:not(:disabled), input:not(:disabled), [href], [tabindex]:not([tabindex="-1"])',
+      ),
+    );
+    if (focusable.length === 0) return;
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault();
+      last?.focus();
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault();
+      first?.focus();
+    }
+  };
+
   return (
     <aside
-      className="hidden lg:flex flex-col sticky top-12 h-[calc(100vh-3rem)] flex-shrink-0 bg-card border-r border-border"
-      style={{ width }}
+      id={compact ? "pn-compact-plan-navigator" : undefined}
+      data-pn-plan-navigator={compact ? "true" : undefined}
+      // The compact navigator (Contents / Versions / Archive) is the same kind
+      // of full-viewport transient surface as CompactPlanStage, so it must not
+      // print over the document either. Desktop rail printing is unchanged.
+      data-print-hide={compact ? true : undefined}
+      role={compact ? "dialog" : undefined}
+      aria-modal={compact ? true : undefined}
+      aria-label={compact ? "Plan navigator" : undefined}
+      onKeyDown={compact ? handleCompactKeyDown : undefined}
+      className={compact
+        ? "pn-visible-viewport-stage z-[90] flex flex-col overflow-hidden bg-card text-foreground"
+        : "hidden lg:flex flex-col sticky top-12 h-[calc(100vh-3rem)] flex-shrink-0 bg-card border-r border-border"}
+      style={{ width: compact ? undefined : width }}
     >
+      {compact && (
+        <div className="flex h-[52px] flex-shrink-0 items-center justify-between border-b border-border/50 px-3">
+          <div className="min-w-0">
+            <p className="text-sm font-semibold tracking-tight">Navigate</p>
+            <p className="truncate text-[11px] text-muted-foreground" aria-live="polite">
+              {pendingFileLabel ? `Opening ${pendingFileLabel}…` : 'Choose what to review'}
+            </p>
+          </div>
+          <button
+            ref={closeButtonRef}
+            type="button"
+            onClick={onClose}
+            data-pn-touch-target="true"
+            data-pn-touch-target-icon="true"
+            className="flex h-9 w-9 items-center justify-center rounded-lg text-muted-foreground outline-none transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/60"
+            aria-label="Close navigator"
+            title="Close navigator"
+          >
+            <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2} aria-hidden="true">
+              <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+      )}
+
       {/* Tab bar */}
-      <div className="flex h-10 items-center border-b border-border/50 px-2 gap-0.5 flex-shrink-0 overflow-hidden min-w-0">
-        {showAgentTerminalButton && onToggleAgentTerminal && (
+      <div className={compact
+        ? "flex min-h-11 items-center gap-1 overflow-x-auto border-b border-border/50 px-2 py-1"
+        : "flex h-10 items-center border-b border-border/50 px-2 gap-0.5 flex-shrink-0 overflow-hidden min-w-0"}
+      >
+        {!compact && showAgentTerminalButton && onToggleAgentTerminal && (
           <ActionButton
             active={!!isAgentTerminalOpen}
             running={!!isAgentTerminalRunning}
@@ -137,26 +219,29 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
             label="Agent"
           />
         )}
-        <TabButton
-          active={activeTab === "toc"}
-          onClick={() => onTabChange("toc")}
-          icon={
-            <svg
-              className="w-3 h-3"
-              fill="none"
-              viewBox="0 0 24 24"
-              stroke="currentColor"
-              strokeWidth={2}
-            >
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                d="M4 6h16M4 10h16M4 14h10M4 18h10"
-              />
-            </svg>
-          }
-          label="Contents"
-        />
+        {showContentsTab && (
+          <TabButton
+            active={activeTab === "toc"}
+            onClick={() => onTabChange("toc")}
+            icon={
+              <svg
+                className="w-3 h-3"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                strokeWidth={2}
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M4 6h16M4 10h16M4 14h10M4 18h10"
+                />
+              </svg>
+            }
+            label="Contents"
+            touch={compact}
+          />
+        )}
         {showVersionsTab && (
           <TabButton
             active={activeTab === "versions"}
@@ -177,6 +262,7 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
               </svg>
             }
             label="Versions"
+            touch={compact}
           />
         )}
         {showMessagesTab && (
@@ -186,6 +272,7 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
             icon={<MessagesIcon className="w-3 h-3" />}
             label="Messages"
             badge={messageAnnotationCounts !== undefined && messageAnnotationCounts.size > 0}
+            touch={compact}
           />
         )}
         {showFilesTab && (
@@ -209,6 +296,7 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
             }
             label="Files"
             badge={hasFileAnnotations}
+            touch={compact}
           />
         )}
         {showArchiveTab && (
@@ -231,6 +319,7 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
               </svg>
             }
             label="Archive"
+            touch={compact}
           />
         )}
         {/* No header close button — the sidebar collapses via the resize-handle
@@ -238,8 +327,11 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
       </div>
 
       {/* Content area */}
-      <OverlayScrollArea className="flex-1 min-h-0">
-        {activeTab === "toc" && (
+      <OverlayScrollArea className={compact
+        ? "flex-1 min-h-0 overscroll-contain [-webkit-overflow-scrolling:touch]"
+        : "flex-1 min-h-0"}
+      >
+        {activeTab === "toc" && showContentsTab && (
           <TableOfContents
             blocks={blocks}
             annotations={annotations}
@@ -280,6 +372,7 @@ export const SidebarContainer: React.FC<SidebarContainerProps> = ({
             annotationCounts={fileAnnotationCounts}
             highlightedFiles={highlightedFiles}
             editStatuses={fileEditStatuses}
+            selectionPending={compact && !!pendingFileLabel}
           />
         )}
         {activeTab === "archive" && showArchiveTab && (
@@ -309,10 +402,13 @@ const TabButton: React.FC<{
   icon: React.ReactNode;
   label: string;
   badge?: boolean;
-}> = ({ active, onClick, icon, label, badge }) => (
+  touch?: boolean;
+}> = ({ active, onClick, icon, label, badge, touch = false }) => (
   <button
+    type="button"
     onClick={onClick}
-    className={`relative flex items-center gap-1 px-2 py-1 rounded text-xs font-medium transition-colors min-w-0 shrink-0 ${
+    data-pn-touch-target={touch ? "true" : undefined}
+    className={`relative flex items-center gap-1 px-2 py-1 rounded text-xs font-medium transition-colors min-w-0 shrink-0${touch ? " h-9" : ""} ${
       active
         ? "bg-primary/10 text-primary"
         : "text-muted-foreground hover:text-foreground hover:bg-muted/50"

package/components/ui/button.tsx

@@ -18,15 +18,15 @@ const buttonVariants = cva(
   {
     variants: {
       variant: {
-        default: "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",
+        default: "bg-primary text-primary-foreground shadow-xs [@media(hover:hover)_and_(pointer:fine)]:hover:bg-primary/90",
         destructive:
-          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40",
-        success: "bg-success text-success-foreground shadow-xs hover:bg-success/90",
+          "bg-destructive text-white shadow-xs [@media(hover:hover)_and_(pointer:fine)]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40",
+        success: "bg-success text-success-foreground shadow-xs [@media(hover:hover)_and_(pointer:fine)]:hover:bg-success/90",
         outline:
-          "border border-input bg-background shadow-xs hover:bg-accent hover:text-accent-foreground",
-        secondary: "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",
-        ghost: "hover:bg-accent hover:text-accent-foreground",
-        link: "text-primary underline-offset-4 hover:underline",
+          "border border-input bg-background shadow-xs [@media(hover:hover)_and_(pointer:fine)]:hover:bg-accent [@media(hover:hover)_and_(pointer:fine)]:hover:text-accent-foreground",
+        secondary: "bg-secondary text-secondary-foreground shadow-xs [@media(hover:hover)_and_(pointer:fine)]:hover:bg-secondary/80",
+        ghost: "[@media(hover:hover)_and_(pointer:fine)]:hover:bg-accent [@media(hover:hover)_and_(pointer:fine)]:hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 [@media(hover:hover)_and_(pointer:fine)]:hover:underline",
       },
       size: {
         default: "h-9 px-4 py-2",
@@ -61,9 +61,11 @@ function Button({
   }) {
   return (
     <ButtonPrimitive
+      {...props}
       data-slot="button"
+      data-pn-touch-target="true"
+      data-pn-touch-target-icon={size === "icon" ? "true" : undefined}
       className={cn(buttonVariants({ variant, size, className }))}
-      {...props}
     >
       {iconLeft ? (
         <span data-slot="button-icon" data-side="left" aria-hidden="true" className="shrink-0">

package/components/ui/dialog.tsx

@@ -14,6 +14,7 @@ const DialogOverlay = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <DialogPrimitive.Backdrop
     ref={ref}
+    data-slot="dialog-overlay"
     className={cn(
       "fixed inset-0 z-[110] bg-black/55 backdrop-blur-[2px]",
       "transition-opacity duration-200",
@@ -28,34 +29,43 @@ DialogOverlay.displayName = "DialogOverlay";
 const DialogContent = React.forwardRef<
   React.ComponentRef<typeof DialogPrimitive.Popup>,
   React.ComponentPropsWithoutRef<typeof DialogPrimitive.Popup> & {
+    /** Optional visual override for the backdrop rendered with this content. */
+    backdropClassName?: string;
+    /** Removes the default top-right close control. */
     hideClose?: boolean;
   }
->(({ className, children, hideClose, ...props }, ref) => (
+>(({ backdropClassName, className, children, hideClose, ...props }, ref) => (
   <DialogPortal>
-    <DialogOverlay />
-    <DialogPrimitive.Popup
-      ref={ref}
-      className={cn(
-        "fixed top-[50%] left-[50%] z-[110] w-full translate-x-[-50%] translate-y-[-50%]",
-        "max-w-4xl max-h-[min(640px,85vh)]",
-        "flex flex-col overflow-hidden",
-        "rounded-2xl border border-border bg-popover text-popover-foreground",
-        "shadow-[0_24px_80px_-36px_rgba(15,23,42,0.5)]",
-        "transition-[opacity,scale] duration-200",
-        "data-starting-style:opacity-0 data-starting-style:scale-95",
-        "data-ending-style:opacity-0 data-ending-style:scale-95",
-        className,
-      )}
-      {...props}
-    >
-      {children}
-      {!hideClose && (
-        <DialogPrimitive.Close className="absolute top-3.5 right-3.5 rounded-md p-1.5 text-muted-foreground hover:text-foreground focus:outline-none focus:ring-2 focus:ring-ring/50">
-          <X className="size-4" />
-          <span className="sr-only">Close</span>
-        </DialogPrimitive.Close>
-      )}
-    </DialogPrimitive.Popup>
+    <DialogOverlay className={backdropClassName} />
+    <div className="pn-visible-viewport-overlay z-[110] pointer-events-none flex items-center justify-center">
+      <DialogPrimitive.Popup
+        ref={ref}
+        className={cn(
+          "relative pointer-events-auto z-[110] w-full min-h-0",
+          "max-w-4xl max-h-[min(640px,85vh,100%)]",
+          "flex flex-col overflow-hidden",
+          "rounded-2xl border border-border bg-popover text-popover-foreground",
+          "shadow-[0_24px_80px_-36px_rgba(15,23,42,0.5)]",
+          "transition-[opacity,scale] duration-200",
+          "data-starting-style:opacity-0 data-starting-style:scale-95",
+          "data-ending-style:opacity-0 data-ending-style:scale-95",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+        {!hideClose && (
+          <DialogPrimitive.Close
+            data-pn-touch-target="true"
+            data-pn-touch-target-icon="true"
+            className="absolute top-3.5 right-3.5 inline-flex items-center justify-center rounded-md p-1.5 text-muted-foreground [@media(hover:hover)_and_(pointer:fine)]:hover:text-foreground focus:outline-none focus:ring-2 focus:ring-ring/50"
+          >
+            <X className="size-4" />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Popup>
+    </div>
   </DialogPortal>
 ));
 DialogContent.displayName = "DialogContent";

package/config/index.ts

@@ -1,4 +1,9 @@
 export { configStore } from './configStore';
 export type { ServerSyncFn } from './configStore';
 export { useConfigValue } from './useConfig';
-export { setReviewPanelView, setReviewDefaultDiffType, type ReviewDefaultDiffType } from './reviewView';
+export {
+  setReviewPanelView,
+  setReviewDefaultDiffType,
+  getPersistedReviewPanelView,
+  type ReviewDefaultDiffType,
+} from './reviewView';

package/config/reviewView.ts

@@ -1,4 +1,5 @@
 import { configStore } from './configStore';
+import { SETTINGS } from './settings';
 
 /**
  * The ONLY writers for the coupled setting pair (reviewPanelView,
@@ -17,13 +18,39 @@ import { configStore } from './configStore';
  * setting directly — always go through these setters. configStore.init()
  * remains the one non-writer that can produce a conflicted pair from a
  * stale config.json; the App-level load reconciler heals that case by
- * calling setReviewPanelView('sections').
+ * calling setReviewPanelView('sections', { recordLastUsed: false }).
  */
-export function setReviewPanelView(view: 'sections' | 'tree'): void {
-  configStore.set('reviewPanelView', view);
-  if (view === 'sections' && configStore.get('defaultDiffType') !== 'since-base') {
-    configStore.set('defaultDiffType', 'since-base');
+
+/** Store seam for tests (fresh ConfigStoreForTest); production always uses the singleton. */
+type PanelViewConfigStore = typeof configStore;
+
+export function setReviewPanelView(
+  view: 'sections' | 'tree',
+  options?: { recordLastUsed?: boolean },
+  store: PanelViewConfigStore = configStore,
+): void {
+  store.set('reviewPanelView', view);
+  // An explicit persisted choice also becomes the last-used view — otherwise
+  // a stale last-used cookie would immediately shadow what the user just
+  // picked in Settings / the setup dialog. recordLastUsed: false is for
+  // NON-choices: the App self-heal repairs a conflicted persisted pair
+  // without any user action, so it must not overwrite the user's memo.
+  if (options?.recordLastUsed !== false) {
+    store.set('reviewPanelViewLastUsed', view);
   }
+  if (view === 'sections' && store.get('defaultDiffType') !== 'since-base') {
+    store.set('defaultDiffType', 'since-base');
+  }
+}
+
+/**
+ * The panel view the reviewer has actually persisted, or `undefined` when they
+ * never chose one. Distinct from `configStore.get('reviewPanelView')`, which
+ * cannot tell a stored choice apart from the built-in default, which is the
+ * difference first-run seeding has to respect before it writes over anything.
+ */
+export function getPersistedReviewPanelView(): 'sections' | 'tree' | undefined {
+  return SETTINGS.reviewPanelView.fromCookie();
 }
 
 export type ReviewDefaultDiffType =
@@ -34,9 +61,15 @@ export type ReviewDefaultDiffType =
   | 'merge-base'
   | 'all';
 
-export function setReviewDefaultDiffType(value: ReviewDefaultDiffType): void {
-  configStore.set('defaultDiffType', value);
-  if (value !== 'since-base' && configStore.get('reviewPanelView') !== 'tree') {
-    configStore.set('reviewPanelView', 'tree');
+export function setReviewDefaultDiffType(
+  value: ReviewDefaultDiffType,
+  store: PanelViewConfigStore = configStore,
+): void {
+  store.set('defaultDiffType', value);
+  if (value !== 'since-base' && store.get('reviewPanelView') !== 'tree') {
+    store.set('reviewPanelView', 'tree');
+    // The snap is an explicit-choice consequence (the user picked a classic
+    // diff default), so it syncs the memo like any explicit view write.
+    store.set('reviewPanelViewLastUsed', 'tree');
   }
 }

package/config/settings.ts

@@ -9,7 +9,12 @@
  * Add new settings here. Cookie-only settings omit serverKey.
  */
 
+import {
+  isAnnotateAgentTerminalSide,
+  type AnnotateAgentTerminalSide,
+} from '@plannotator/core/agent-terminal';
 import type { DiffLineBgIntensity } from '@plannotator/core/config-types';
+import { isFaviconStyle, type FaviconStyle } from '@plannotator/core/favicon';
 import { storage } from '../utils/storage';
 import { generateIdentity } from '../utils/generateIdentity';
 import {
@@ -131,6 +136,20 @@ export const SETTINGS = {
     },
     toServer: (v: ThemePair) => ({ theme: { mode: v.mode, light: v.light, dark: v.dark } }),
   },
+  faviconStyle: {
+    defaultValue: 'totman' as FaviconStyle,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-favicon');
+      return isFaviconStyle(v) ? v : undefined;
+    },
+    toCookie: (v: FaviconStyle) => storage.setItem('plannotator-favicon', v),
+    serverKey: 'favicon',
+    fromServer: (sc: Record<string, unknown>) => {
+      const v = sc.favicon;
+      return isFaviconStyle(v) ? v : undefined;
+    },
+    toServer: (v: FaviconStyle) => ({ favicon: v }),
+  },
 
   gridEnabled: {
     // Default ON: plans open in the classic grid / floating-card look. The UI 2.0
@@ -205,6 +224,54 @@ export const SETTINGS = {
     serverKey: undefined, fromServer: undefined, toServer: undefined,
   },
 
+  // The view the user last SELECTED via the in-review header toggle. Layered
+  // between the session state and the persisted reviewPanelView default, so a
+  // new session opens on what the user was actually using. Cookie-only.
+  // null = no last-used recorded (fall through to reviewPanelView).
+  //
+  // 'commits' is never recorded here for the same reason reviewPanelView
+  // rejects it: the Commits view is session-only and never an opening view.
+  reviewPanelViewLastUsed: {
+    defaultValue: null as 'sections' | 'tree' | null,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-review-panel-view-last-used');
+      return v === 'tree' || v === 'sections' ? v : undefined;
+    },
+    toCookie: (v: 'sections' | 'tree' | null) => {
+      // The null default seeds through here on first load — "unrecorded" has
+      // no cookie representation, so write nothing.
+      if (v === 'sections' || v === 'tree') {
+        storage.setItem('plannotator-review-panel-view-last-used', v);
+      }
+    },
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
+  // Compact left-panel preferences. These are deliberately cookie-only: they
+  // shape the local file-list chrome without changing review semantics or the
+  // repository state, and should follow the reviewer across review sessions.
+  reviewShowViewedControls: {
+    defaultValue: true as boolean,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-review-show-viewed-controls');
+      return value === 'true' ? true : value === 'false' ? false : undefined;
+    },
+    toCookie: (value: boolean) =>
+      storage.setItem('plannotator-review-show-viewed-controls', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
+  reviewShowStageControls: {
+    defaultValue: true as boolean,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-review-show-stage-controls');
+      return value === 'true' ? true : value === 'false' ? false : undefined;
+    },
+    toCookie: (value: boolean) =>
+      storage.setItem('plannotator-review-show-stage-controls', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
   defaultDiffType: {
     defaultValue: 'since-base' as 'since-base' | 'uncommitted' | 'unstaged' | 'staged' | 'merge-base' | 'all',
     fromCookie: () => {
@@ -414,6 +481,36 @@ export const SETTINGS = {
     fromServer: undefined,
     toServer: undefined,
   },
+  semanticDiffEnabled: {
+    defaultValue: true as boolean,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-semantic-diff-enabled');
+      return value === 'true' ? true : value === 'false' ? false : undefined;
+    },
+    toCookie: (value: boolean) =>
+      storage.setItem('plannotator-semantic-diff-enabled', String(value)),
+    serverKey: 'reviewAnalysis',
+    fromServer: (serverConfig: Record<string, unknown>) => {
+      const value = (serverConfig.reviewAnalysis as Record<string, unknown> | undefined)?.semanticDiff;
+      return typeof value === 'boolean' ? value : undefined;
+    },
+    toServer: (value: boolean) => ({ reviewAnalysis: { semanticDiff: value } }),
+  },
+  callFlowEnabled: {
+    defaultValue: false as boolean,
+    fromCookie: () => {
+      const value = storage.getItem('plannotator-call-flow-enabled');
+      return value === 'true' ? true : value === 'false' ? false : undefined;
+    },
+    toCookie: (value: boolean) =>
+      storage.setItem('plannotator-call-flow-enabled', String(value)),
+    serverKey: 'reviewAnalysis',
+    fromServer: (serverConfig: Record<string, unknown>) => {
+      const value = (serverConfig.reviewAnalysis as Record<string, unknown> | undefined)?.callFlow;
+      return typeof value === 'boolean' ? value : undefined;
+    },
+    toServer: (value: boolean) => ({ reviewAnalysis: { callFlow: value } }),
+  },
   conventionalComments: {
     defaultValue: false as boolean,
     fromCookie: () => {
@@ -453,6 +550,50 @@ export const SETTINGS = {
       }
     },
   },
+  /**
+   * Where the annotate-mode Agent TUI docks: 'left' (where it always docked),
+   * 'right', or 'hidden' (no slot until the user opens it for the session).
+   *
+   * Server-synced so the placement survives the random port every annotate
+   * session runs on — a cookie alone is per-origin, and each invocation is a
+   * new origin, so a cookie-only preference is effectively per-session.
+   *
+   * The cookie key is the pre-registry one, so a user who already picked a
+   * side keeps it across the upgrade.
+   */
+  agentTerminalSide: {
+    defaultValue: 'left' as AnnotateAgentTerminalSide,
+    fromCookie: () => {
+      const v = storage.getItem('plannotator-annotate-agent-terminal-side');
+      return isAnnotateAgentTerminalSide(v) ? v : undefined;
+    },
+    toCookie: (v: AnnotateAgentTerminalSide) =>
+      storage.setItem('plannotator-annotate-agent-terminal-side', v),
+    serverKey: 'agentTerminalSide',
+    fromServer: (sc: Record<string, unknown>) =>
+      isAnnotateAgentTerminalSide(sc.agentTerminalSide) ? sc.agentTerminalSide : undefined,
+    toServer: (v: AnnotateAgentTerminalSide) => ({ agentTerminalSide: v }),
+  },
+  /**
+   * Which agent the annotate-mode Agent TUI preselects. Empty string = no
+   * choice recorded yet, in which case the first available agent wins.
+   * Server-synced for the same reason as the placement above.
+   */
+  agentTerminalDefaultAgent: {
+    defaultValue: '' as string,
+    fromCookie: () =>
+      storage.getItem('plannotator-annotate-agent-terminal-default') || undefined,
+    toCookie: (v: string) => {
+      if (v) storage.setItem('plannotator-annotate-agent-terminal-default', v);
+      else storage.removeItem('plannotator-annotate-agent-terminal-default');
+    },
+    serverKey: 'agentTerminalDefaultAgent',
+    fromServer: (sc: Record<string, unknown>) =>
+      typeof sc.agentTerminalDefaultAgent === 'string' && sc.agentTerminalDefaultAgent
+        ? sc.agentTerminalDefaultAgent
+        : undefined,
+    toServer: (v: string) => ({ agentTerminalDefaultAgent: v }),
+  },
   /* SettingDef<any>, not <unknown>: consumers compile this shipped source under
      their own strictFunctionTypes, where a narrow `toCookie: (v: string) => void`
      is contravariantly incompatible with `(value: unknown) => void`. */

package/hooks/useAIProviderConfig.ts

@@ -59,14 +59,15 @@ export function useAIProviderConfig({
   // Auto-resolve provider/model once capabilities are known.
   useEffect(() => {
     if (!available || providers.length === 0) return;
+    const saved = getAIProviderSettings();
+    const selection = resolveAIProviderSelection({
+      providers,
+      origin,
+      settings: saved,
+      serverDefaultProvider: defaultProvider,
+    });
+
     setAiConfig(prev => {
-      const saved = getAIProviderSettings();
-      const selection = resolveAIProviderSelection({
-        providers,
-        origin,
-        settings: saved,
-        serverDefaultProvider: defaultProvider,
-      });
       if (prev.providerId === selection.providerId && prev.model === selection.model) return prev;
       return {
         ...prev,