From c98bf45d831a8c645ddcd30291edac75b6d2248f Mon Sep 17 00:00:00 2001
From: Ronald Roy <gsdwig@gmail.com>
Date: Wed, 21 Jan 2026 06:13:56 -0800
Subject: [PATCH 1/2] feat: Add snapshot hover preview in Pair Writing toolbar

Shows truncated snapshot content (500 chars or 15 lines) when hovering
over the Snapshot button, giving users a quick view of what they captured
without needing to compare.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 frontend/src/components/PairWritingMode.css   | 40 +++++++++
 frontend/src/components/PairWritingMode.tsx   |  1 +
 .../src/components/PairWritingToolbar.tsx     | 89 ++++++++++++++-----
 .../__tests__/PairWritingToolbar.test.tsx     | 83 +++++++++++++++++
 4 files changed, 191 insertions(+), 22 deletions(-)

diff --git a/frontend/src/components/PairWritingMode.css b/frontend/src/components/PairWritingMode.css
index 70964e33..46e8d0d1 100644
--- a/frontend/src/components/PairWritingMode.css
+++ b/frontend/src/components/PairWritingMode.css
@@ -33,6 +33,8 @@
   backdrop-filter: blur(var(--glass-blur));
   min-height: 48px;
   gap: var(--spacing-md);
+  position: relative;
+  z-index: 11; /* Above content panes and (+) for snapshot preview popover. */
 }
 
 @supports not (backdrop-filter: blur(10px)) {
@@ -124,6 +126,44 @@
   background: var(--color-accent-primary-a15);
 }
 
+/* Snapshot button wrapper for hover preview positioning */
+.pair-writing-toolbar__snapshot-wrapper {
+  position: relative;
+}
+
+/* Snapshot preview popover */
+.pair-writing-toolbar__snapshot-preview {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  margin-top: var(--spacing-xs);
+  min-width: 300px;
+  max-width: 500px;
+  max-height: 300px;
+  overflow-y: auto;
+  background: var(--color-surface);
+  border: 1px solid var(--glass-border);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-lg);
+  z-index: 100;
+  padding: var(--spacing-sm);
+}
+
+.pair-writing-toolbar__snapshot-preview-content {
+  margin: 0;
+  font-family: var(--font-mono);
+  font-size: var(--text-xs);
+  line-height: 1.5;
+  color: var(--color-text);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.pair-writing-toolbar__snapshot-preview-ellipsis {
+  color: var(--color-text-secondary);
+  font-style: italic;
+}
+
 /* Save button */
 .pair-writing-toolbar__btn--save {
   background: var(--gradient-primary);
diff --git a/frontend/src/components/PairWritingMode.tsx b/frontend/src/components/PairWritingMode.tsx
index f02f6f52..c953f995 100644
--- a/frontend/src/components/PairWritingMode.tsx
+++ b/frontend/src/components/PairWritingMode.tsx
@@ -227,6 +227,7 @@ export function PairWritingMode({
         onSave={handleSave}
         onExit={handleExitClick}
         filePath={filePath}
+        snapshotContent={state.snapshot ?? undefined}
       />
 
       {/* Split-screen content (REQ-F-11, TD-6) */}
diff --git a/frontend/src/components/PairWritingToolbar.tsx b/frontend/src/components/PairWritingToolbar.tsx
index 81710b11..6f5a49ae 100644
--- a/frontend/src/components/PairWritingToolbar.tsx
+++ b/frontend/src/components/PairWritingToolbar.tsx
@@ -7,7 +7,7 @@
  * @see .sdd/specs/memory-loop/2026-01-20-pair-writing-mode.md REQ-F-14, REQ-F-23, REQ-F-29, REQ-F-30
  */
 
-import React from "react";
+import React, { useState } from "react";
 import "./PairWritingMode.css";
 
 export interface PairWritingToolbarProps {
@@ -25,6 +25,8 @@ export interface PairWritingToolbarProps {
   onExit: () => void;
   /** Current file path being edited (displayed in toolbar) */
   filePath?: string;
+  /** The actual snapshot text content (for hover preview) */
+  snapshotContent?: string;
 }
 
 /**
@@ -37,6 +39,29 @@ export interface PairWritingToolbarProps {
  *
  * Note: Exit confirmation dialog is handled by the parent PairWritingMode component.
  */
+/**
+ * Truncates snapshot content for preview display.
+ * Limits to ~500 characters or ~15 lines, whichever is shorter.
+ */
+function truncateForPreview(content: string): { text: string; isTruncated: boolean } {
+  const MAX_CHARS = 500;
+  const MAX_LINES = 15;
+
+  const lines = content.split("\n");
+  let result = "";
+  let lineCount = 0;
+
+  for (const line of lines) {
+    if (lineCount >= MAX_LINES || result.length + line.length > MAX_CHARS) {
+      return { text: result.trimEnd(), isTruncated: true };
+    }
+    result += (lineCount > 0 ? "\n" : "") + line;
+    lineCount++;
+  }
+
+  return { text: result, isTruncated: false };
+}
+
 export function PairWritingToolbar({
   hasUnsavedChanges,
   hasSnapshot,
@@ -45,7 +70,9 @@ export function PairWritingToolbar({
   onSave,
   onExit,
   filePath,
+  snapshotContent,
 }: PairWritingToolbarProps): React.ReactNode {
+  const [isHoveringSnapshot, setIsHoveringSnapshot] = useState(false);
   return (
     <div className="pair-writing-toolbar" role="toolbar" aria-label="Pair Writing toolbar">
       {/* Left section: file info */}
@@ -64,29 +91,47 @@ export function PairWritingToolbar({
 
       {/* Right section: action buttons */}
       <div className="pair-writing-toolbar__actions">
-        {/* Snapshot button (REQ-F-23) */}
-        <button
-          type="button"
-          className={`pair-writing-toolbar__btn pair-writing-toolbar__btn--snapshot${hasSnapshot ? " pair-writing-toolbar__btn--has-snapshot" : ""}`}
-          onClick={onSnapshot}
-          aria-pressed={hasSnapshot}
-          title={hasSnapshot ? "Update snapshot (replaces previous)" : "Take snapshot for comparison"}
+        {/* Snapshot button with hover preview (REQ-F-23) */}
+        <div
+          className="pair-writing-toolbar__snapshot-wrapper"
+          onMouseEnter={() => setIsHoveringSnapshot(true)}
+          onMouseLeave={() => setIsHoveringSnapshot(false)}
         >
-          <svg
-            className="pair-writing-toolbar__icon"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="2"
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            aria-hidden="true"
+          <button
+            type="button"
+            className={`pair-writing-toolbar__btn pair-writing-toolbar__btn--snapshot${hasSnapshot ? " pair-writing-toolbar__btn--has-snapshot" : ""}`}
+            onClick={onSnapshot}
+            aria-pressed={hasSnapshot}
+            title={hasSnapshot ? "Update snapshot (replaces previous)" : "Take snapshot for comparison"}
           >
-            <path d="M23 19a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4l2-3h6l2 3h4a2 2 0 0 1 2 2z" />
-            <circle cx="12" cy="13" r="4" />
-          </svg>
-          <span className="pair-writing-toolbar__label">Snapshot</span>
-        </button>
+            <svg
+              className="pair-writing-toolbar__icon"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              aria-hidden="true"
+            >
+              <path d="M23 19a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4l2-3h6l2 3h4a2 2 0 0 1 2 2z" />
+              <circle cx="12" cy="13" r="4" />
+            </svg>
+            <span className="pair-writing-toolbar__label">Snapshot</span>
+          </button>
+          {/* Snapshot preview popover */}
+          {hasSnapshot && isHoveringSnapshot && snapshotContent && (() => {
+            const { text, isTruncated } = truncateForPreview(snapshotContent);
+            return (
+              <div className="pair-writing-toolbar__snapshot-preview" role="tooltip">
+                <pre className="pair-writing-toolbar__snapshot-preview-content">
+                  {text}
+                  {isTruncated && <span className="pair-writing-toolbar__snapshot-preview-ellipsis">...</span>}
+                </pre>
+              </div>
+            );
+          })()}
+        </div>
 
         {/* Save button (REQ-F-29) */}
         <button
diff --git a/frontend/src/components/__tests__/PairWritingToolbar.test.tsx b/frontend/src/components/__tests__/PairWritingToolbar.test.tsx
index 22a28b35..cc14eeef 100644
--- a/frontend/src/components/__tests__/PairWritingToolbar.test.tsx
+++ b/frontend/src/components/__tests__/PairWritingToolbar.test.tsx
@@ -85,6 +85,89 @@ describe("PairWritingToolbar", () => {
       rerender(<PairWritingToolbar {...defaultProps} hasSnapshot={true} />);
       expect(screen.getByTitle("Update snapshot (replaces previous)")).toBeDefined();
     });
+
+    it("shows preview on hover when snapshot content exists", () => {
+      render(
+        <PairWritingToolbar
+          {...defaultProps}
+          hasSnapshot={true}
+          snapshotContent="# Test Snapshot\n\nThis is the snapshot content."
+        />
+      );
+
+      // Preview should not be visible initially
+      expect(screen.queryByRole("tooltip")).toBeNull();
+
+      // Hover over the snapshot wrapper
+      const wrapper = document.querySelector(".pair-writing-toolbar__snapshot-wrapper");
+      expect(wrapper).not.toBeNull();
+      fireEvent.mouseEnter(wrapper!);
+
+      // Preview should now be visible
+      const preview = screen.getByRole("tooltip");
+      expect(preview).toBeDefined();
+      expect(preview.textContent).toContain("Test Snapshot");
+    });
+
+    it("hides preview on mouse leave", () => {
+      render(
+        <PairWritingToolbar
+          {...defaultProps}
+          hasSnapshot={true}
+          snapshotContent="# Test Snapshot"
+        />
+      );
+
+      const wrapper = document.querySelector(".pair-writing-toolbar__snapshot-wrapper");
+      fireEvent.mouseEnter(wrapper!);
+      expect(screen.getByRole("tooltip")).toBeDefined();
+
+      fireEvent.mouseLeave(wrapper!);
+      expect(screen.queryByRole("tooltip")).toBeNull();
+    });
+
+    it("truncates long snapshot content with ellipsis", () => {
+      // Generate content longer than 500 chars or 15 lines
+      const longContent = Array(20).fill("This is a line of text.").join("\n");
+      render(
+        <PairWritingToolbar
+          {...defaultProps}
+          hasSnapshot={true}
+          snapshotContent={longContent}
+        />
+      );
+
+      const wrapper = document.querySelector(".pair-writing-toolbar__snapshot-wrapper");
+      fireEvent.mouseEnter(wrapper!);
+
+      const ellipsis = document.querySelector(".pair-writing-toolbar__snapshot-preview-ellipsis");
+      expect(ellipsis).not.toBeNull();
+      expect(ellipsis?.textContent).toBe("...");
+    });
+
+    it("does not show preview when hasSnapshot is false", () => {
+      render(
+        <PairWritingToolbar
+          {...defaultProps}
+          hasSnapshot={false}
+          snapshotContent="# Some content"
+        />
+      );
+
+      const wrapper = document.querySelector(".pair-writing-toolbar__snapshot-wrapper");
+      fireEvent.mouseEnter(wrapper!);
+
+      expect(screen.queryByRole("tooltip")).toBeNull();
+    });
+
+    it("does not show preview when snapshotContent is undefined", () => {
+      render(<PairWritingToolbar {...defaultProps} hasSnapshot={true} />);
+
+      const wrapper = document.querySelector(".pair-writing-toolbar__snapshot-wrapper");
+      fireEvent.mouseEnter(wrapper!);
+
+      expect(screen.queryByRole("tooltip")).toBeNull();
+    });
   });
 
   describe("save button (REQ-F-29)", () => {

From 0d616b68f0fa314349a19271f7ed900daaad4069 Mon Sep 17 00:00:00 2001
From: Ronald Roy <gsdwig@gmail.com>
Date: Wed, 21 Jan 2026 06:27:51 -0800
Subject: [PATCH 2/2] fix: Change snapshot to capture selected text, not entire
 file

The snapshot feature now captures the currently selected text instead of
the entire document. This enables a more useful workflow:
1. Select text you want to rework
2. Click Snapshot to capture it
3. Edit the section
4. Select new version and Compare to see changes

The Snapshot button is now disabled when no text is selected.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 frontend/src/components/PairWritingEditor.tsx |  8 +++
 frontend/src/components/PairWritingMode.tsx   | 17 +++++--
 .../src/components/PairWritingToolbar.tsx     | 15 +++++-
 .../__tests__/PairWritingMode.test.tsx        | 30 ++++++++----
 .../__tests__/PairWritingToolbar.test.tsx     | 29 ++++++++---
 .../src/hooks/usePairWritingState.test.ts     | 49 +++++++++----------
 frontend/src/hooks/usePairWritingState.ts     | 13 ++---
 7 files changed, 109 insertions(+), 52 deletions(-)

diff --git a/frontend/src/components/PairWritingEditor.tsx b/frontend/src/components/PairWritingEditor.tsx
index 74bf5b38..266be921 100644
--- a/frontend/src/components/PairWritingEditor.tsx
+++ b/frontend/src/components/PairWritingEditor.tsx
@@ -43,6 +43,8 @@ export interface PairWritingEditorProps {
     action: QuickActionType,
     selection: SelectionContext
   ) => void;
+  /** Called when text selection changes (null when no selection) */
+  onSelectionChange?: (selection: SelectionContext | null) => void;
   hasSnapshot?: boolean;
   snapshotContent?: string;
   /** Dependency injection for testing */
@@ -58,6 +60,7 @@ export function PairWritingEditor({
   onQuickActionComplete,
   onAdvisoryAction,
   onQuickAction,
+  onSelectionChange,
   hasSnapshot = false,
   ContextMenuComponent = EditorContextMenu,
 }: PairWritingEditorProps): React.ReactNode {
@@ -71,6 +74,11 @@ export function PairWritingEditor({
 
   const { selection } = useTextSelection(textareaRef, content);
 
+  // Notify parent when selection changes
+  useEffect(() => {
+    onSelectionChange?.(selection);
+  }, [selection, onSelectionChange]);
+
   // Refs for stable callback access to current values
   const selectionRef = useRef<SelectionContext | null>(null);
   selectionRef.current = selection;
diff --git a/frontend/src/components/PairWritingMode.tsx b/frontend/src/components/PairWritingMode.tsx
index c953f995..d337cd66 100644
--- a/frontend/src/components/PairWritingMode.tsx
+++ b/frontend/src/components/PairWritingMode.tsx
@@ -24,7 +24,7 @@ import { PairWritingEditor } from "./PairWritingEditor";
 import { Discussion } from "./Discussion";
 import { ConfirmDialog } from "./ConfirmDialog";
 import type { AdvisoryActionType, QuickActionType } from "./EditorContextMenu";
-import type { SelectionContext } from "../hooks/useTextSelection";
+import { type SelectionContext } from "../hooks/useTextSelection";
 import type { ConnectionStatus } from "../hooks/useWebSocket";
 import "./PairWritingMode.css";
 
@@ -89,6 +89,7 @@ export function PairWritingMode({
   const { addMessage } = useSession();
   const [showExitConfirm, setShowExitConfirm] = useState(false);
   const [isSaving, setIsSaving] = useState(false);
+  const [currentSelection, setCurrentSelection] = useState<SelectionContext | null>(null);
 
   // Track previous initialContent to detect external changes (not local edits)
   const prevInitialContent = useRef(initialContent);
@@ -110,10 +111,18 @@ export function PairWritingMode({
     }
   }, [initialContent, state.isActive, actions]);
 
+  // Handle selection changes from editor
+  const handleSelectionChange = useCallback((selection: SelectionContext | null) => {
+    setCurrentSelection(selection);
+  }, []);
+
   // Handle snapshot button (REQ-F-23)
+  // Captures the currently selected text, not the entire file
   const handleSnapshot = useCallback(() => {
-    actions.takeSnapshot();
-  }, [actions]);
+    if (currentSelection?.text) {
+      actions.takeSnapshot(currentSelection.text);
+    }
+  }, [actions, currentSelection]);
 
   // Handle save button (REQ-F-29)
   const handleSave = useCallback(() => {
@@ -222,6 +231,7 @@ export function PairWritingMode({
       <PairWritingToolbar
         hasUnsavedChanges={state.hasUnsavedChanges}
         hasSnapshot={state.snapshot !== null}
+        hasSelection={currentSelection !== null}
         isSaving={isSaving}
         onSnapshot={handleSnapshot}
         onSave={handleSave}
@@ -243,6 +253,7 @@ export function PairWritingMode({
             onQuickActionComplete={handleQuickActionComplete}
             onQuickAction={handleQuickAction}
             onAdvisoryAction={handleAdvisoryAction}
+            onSelectionChange={handleSelectionChange}
             hasSnapshot={state.snapshot !== null}
             snapshotContent={state.snapshot ?? undefined}
           />
diff --git a/frontend/src/components/PairWritingToolbar.tsx b/frontend/src/components/PairWritingToolbar.tsx
index 6f5a49ae..3f42b621 100644
--- a/frontend/src/components/PairWritingToolbar.tsx
+++ b/frontend/src/components/PairWritingToolbar.tsx
@@ -15,6 +15,8 @@ export interface PairWritingToolbarProps {
   hasUnsavedChanges: boolean;
   /** Whether a snapshot currently exists (REQ-F-24) */
   hasSnapshot: boolean;
+  /** Whether text is currently selected in the editor */
+  hasSelection?: boolean;
   /** Whether save is in progress */
   isSaving?: boolean;
   /** Called when user clicks Snapshot button (REQ-F-23) */
@@ -65,6 +67,7 @@ function truncateForPreview(content: string): { text: string; isTruncated: boole
 export function PairWritingToolbar({
   hasUnsavedChanges,
   hasSnapshot,
+  hasSelection = false,
   isSaving = false,
   onSnapshot,
   onSave,
@@ -73,6 +76,9 @@ export function PairWritingToolbar({
   snapshotContent,
 }: PairWritingToolbarProps): React.ReactNode {
   const [isHoveringSnapshot, setIsHoveringSnapshot] = useState(false);
+
+  // Snapshot requires a selection (captures selected text, not entire file)
+  const canSnapshot = hasSelection;
   return (
     <div className="pair-writing-toolbar" role="toolbar" aria-label="Pair Writing toolbar">
       {/* Left section: file info */}
@@ -101,8 +107,15 @@ export function PairWritingToolbar({
             type="button"
             className={`pair-writing-toolbar__btn pair-writing-toolbar__btn--snapshot${hasSnapshot ? " pair-writing-toolbar__btn--has-snapshot" : ""}`}
             onClick={onSnapshot}
+            disabled={!canSnapshot}
             aria-pressed={hasSnapshot}
-            title={hasSnapshot ? "Update snapshot (replaces previous)" : "Take snapshot for comparison"}
+            title={
+              !canSnapshot
+                ? "Select text to snapshot"
+                : hasSnapshot
+                  ? "Update snapshot (replaces previous)"
+                  : "Take snapshot of selection"
+            }
           >
             <svg
               className="pair-writing-toolbar__icon"
diff --git a/frontend/src/components/__tests__/PairWritingMode.test.tsx b/frontend/src/components/__tests__/PairWritingMode.test.tsx
index 9a5067d5..da4b3022 100644
--- a/frontend/src/components/__tests__/PairWritingMode.test.tsx
+++ b/frontend/src/components/__tests__/PairWritingMode.test.tsx
@@ -8,14 +8,28 @@
 
 import { describe, it, expect, afterEach, mock } from "bun:test";
 import { render, screen, fireEvent, cleanup, within, waitFor } from "@testing-library/react";
-import type { ReactNode } from "react";
+import { useEffect, type ReactNode } from "react";
 import { PairWritingMode } from "../PairWritingMode";
 import { SessionProvider, useSession } from "../../contexts/SessionContext";
 import type { PairWritingEditorProps } from "../PairWritingEditor";
 import type { SelectionContext } from "../../hooks/useTextSelection";
 
+// Mock selection used across mock editors
+const mockSelection: SelectionContext = {
+  text: "test selection",
+  contextBefore: "before ",
+  contextAfter: " after",
+  startLine: 5,
+  endLine: 5,
+  totalLines: 10,
+};
+
 // Mock components injected via props (no mock.module pollution)
-function MockEditor() {
+function MockEditor(props: PairWritingEditorProps) {
+  // Simulate having a selection so the Snapshot button is enabled
+  useEffect(() => {
+    props.onSelectionChange?.(mockSelection);
+  }, []);
   return <div data-testid="pair-writing-editor">PairWritingEditor</div>;
 }
 
@@ -33,14 +47,10 @@ function MockDiscussion() {
  * Mock editor that exposes callbacks via buttons for testing
  */
 function MockEditorWithCallbacks(props: PairWritingEditorProps) {
-  const mockSelection: SelectionContext = {
-    text: "test selection",
-    contextBefore: "before ",
-    contextAfter: " after",
-    startLine: 5,
-    endLine: 5,
-    totalLines: 10,
-  };
+  // Simulate having a selection so the Snapshot button is enabled
+  useEffect(() => {
+    props.onSelectionChange?.(mockSelection);
+  }, []);
 
   return (
     <div data-testid="pair-writing-editor">
diff --git a/frontend/src/components/__tests__/PairWritingToolbar.test.tsx b/frontend/src/components/__tests__/PairWritingToolbar.test.tsx
index cc14eeef..6c83d19a 100644
--- a/frontend/src/components/__tests__/PairWritingToolbar.test.tsx
+++ b/frontend/src/components/__tests__/PairWritingToolbar.test.tsx
@@ -18,6 +18,7 @@ describe("PairWritingToolbar", () => {
   const defaultProps = {
     hasUnsavedChanges: false,
     hasSnapshot: false,
+    hasSelection: true, // Most tests assume selection exists
     isSaving: false,
     onSnapshot: mock(() => {}),
     onSave: mock(() => {}),
@@ -55,34 +56,48 @@ describe("PairWritingToolbar", () => {
   });
 
   describe("snapshot button (REQ-F-23)", () => {
-    it("calls onSnapshot when clicked", () => {
+    it("calls onSnapshot when clicked with selection", () => {
       const onSnapshot = mock(() => {});
-      render(<PairWritingToolbar {...defaultProps} onSnapshot={onSnapshot} />);
+      render(<PairWritingToolbar {...defaultProps} onSnapshot={onSnapshot} hasSelection={true} />);
 
       fireEvent.click(screen.getByTitle(/snapshot/i));
 
       expect(onSnapshot).toHaveBeenCalledTimes(1);
     });
 
+    it("is disabled when no selection", () => {
+      render(<PairWritingToolbar {...defaultProps} hasSelection={false} />);
+
+      const snapshotBtn = screen.getByTitle("Select text to snapshot");
+      expect(snapshotBtn.hasAttribute("disabled")).toBe(true);
+    });
+
+    it("is enabled when selection exists", () => {
+      render(<PairWritingToolbar {...defaultProps} hasSelection={true} />);
+
+      const snapshotBtn = screen.getByTitle(/take snapshot/i);
+      expect(snapshotBtn.hasAttribute("disabled")).toBe(false);
+    });
+
     it("has aria-pressed false when no snapshot exists", () => {
-      render(<PairWritingToolbar {...defaultProps} hasSnapshot={false} />);
+      render(<PairWritingToolbar {...defaultProps} hasSnapshot={false} hasSelection={true} />);
 
       const snapshotBtn = screen.getByTitle(/take snapshot/i);
       expect(snapshotBtn.getAttribute("aria-pressed")).toBe("false");
     });
 
     it("has aria-pressed true when snapshot exists", () => {
-      render(<PairWritingToolbar {...defaultProps} hasSnapshot={true} />);
+      render(<PairWritingToolbar {...defaultProps} hasSnapshot={true} hasSelection={true} />);
 
       const snapshotBtn = screen.getByTitle(/update snapshot/i);
       expect(snapshotBtn.getAttribute("aria-pressed")).toBe("true");
     });
 
     it("has different title when snapshot exists", () => {
-      const { rerender } = render(<PairWritingToolbar {...defaultProps} hasSnapshot={false} />);
-      expect(screen.getByTitle("Take snapshot for comparison")).toBeDefined();
+      const { rerender } = render(<PairWritingToolbar {...defaultProps} hasSnapshot={false} hasSelection={true} />);
+      expect(screen.getByTitle("Take snapshot of selection")).toBeDefined();
 
-      rerender(<PairWritingToolbar {...defaultProps} hasSnapshot={true} />);
+      rerender(<PairWritingToolbar {...defaultProps} hasSnapshot={true} hasSelection={true} />);
       expect(screen.getByTitle("Update snapshot (replaces previous)")).toBeDefined();
     });
 
diff --git a/frontend/src/hooks/usePairWritingState.test.ts b/frontend/src/hooks/usePairWritingState.test.ts
index aac68fd4..69dc5e9f 100644
--- a/frontend/src/hooks/usePairWritingState.test.ts
+++ b/frontend/src/hooks/usePairWritingState.test.ts
@@ -44,7 +44,7 @@ describe("usePairWritingState", () => {
       // Set up some state
       act(() => {
         result.current.actions.activate("initial content");
-        result.current.actions.takeSnapshot();
+        result.current.actions.takeSnapshot("selected text");
         result.current.actions.setContent("modified content");
       });
 
@@ -66,7 +66,7 @@ describe("usePairWritingState", () => {
       // Set up some state
       act(() => {
         result.current.actions.activate("content");
-        result.current.actions.takeSnapshot();
+        result.current.actions.takeSnapshot("selected text");
         result.current.actions.setContent("modified");
       });
 
@@ -116,33 +116,32 @@ describe("usePairWritingState", () => {
   });
 
   describe("takeSnapshot (REQ-F-23, REQ-F-24)", () => {
-    test("captures current content as snapshot", () => {
+    test("captures selected text as snapshot (not entire file)", () => {
       const { result } = renderHook(() => usePairWritingState());
 
       act(() => {
-        result.current.actions.activate("snapshot this");
-        result.current.actions.takeSnapshot();
+        result.current.actions.activate("full document content here");
+        result.current.actions.takeSnapshot("selected portion");
       });
 
-      expect(result.current.state.snapshot).toBe("snapshot this");
+      expect(result.current.state.snapshot).toBe("selected portion");
     });
 
     test("new snapshot replaces previous (REQ-F-24: only one at a time)", () => {
       const { result } = renderHook(() => usePairWritingState());
 
       act(() => {
-        result.current.actions.activate("first snapshot");
-        result.current.actions.takeSnapshot();
+        result.current.actions.activate("document content");
+        result.current.actions.takeSnapshot("first selection");
       });
 
-      expect(result.current.state.snapshot).toBe("first snapshot");
+      expect(result.current.state.snapshot).toBe("first selection");
 
       act(() => {
-        result.current.actions.setContent("second snapshot");
-        result.current.actions.takeSnapshot();
+        result.current.actions.takeSnapshot("second selection");
       });
 
-      expect(result.current.state.snapshot).toBe("second snapshot");
+      expect(result.current.state.snapshot).toBe("second selection");
     });
   });
 
@@ -152,10 +151,10 @@ describe("usePairWritingState", () => {
 
       act(() => {
         result.current.actions.activate("content");
-        result.current.actions.takeSnapshot();
+        result.current.actions.takeSnapshot("selected text");
       });
 
-      expect(result.current.state.snapshot).toBe("content");
+      expect(result.current.state.snapshot).toBe("selected text");
 
       act(() => {
         result.current.actions.clearSnapshot();
@@ -171,7 +170,7 @@ describe("usePairWritingState", () => {
 
       act(() => {
         result.current.actions.activate("content");
-        result.current.actions.takeSnapshot();
+        result.current.actions.takeSnapshot("selected text");
         result.current.actions.setContent("modified");
       });
 
@@ -230,7 +229,7 @@ describe("usePairWritingState", () => {
 
       act(() => {
         result.current.actions.activate("initial");
-        result.current.actions.takeSnapshot();
+        result.current.actions.takeSnapshot("selected text");
       });
 
       act(() => {
@@ -238,7 +237,7 @@ describe("usePairWritingState", () => {
       });
 
       expect(result.current.state.content).toBe("reloaded");
-      expect(result.current.state.snapshot).toBe("initial");
+      expect(result.current.state.snapshot).toBe("selected text");
     });
   });
 
@@ -268,10 +267,10 @@ describe("usePairWritingState", () => {
 
       act(() => {
         result.current.actions.activate("content");
-        result.current.actions.takeSnapshot();
+        result.current.actions.takeSnapshot("selected text");
       });
 
-      expect(result.current.state.snapshot).toBe("content");
+      expect(result.current.state.snapshot).toBe("selected text");
 
       act(() => {
         result.current.actions.clearAll();
@@ -282,7 +281,7 @@ describe("usePairWritingState", () => {
   });
 
   describe("typical workflow", () => {
-    test("edit-snapshot-compare workflow", () => {
+    test("select-snapshot-edit-compare workflow", () => {
       const { result } = renderHook(() => usePairWritingState());
 
       // 1. Enter Pair Writing Mode with file content
@@ -293,16 +292,16 @@ describe("usePairWritingState", () => {
       expect(result.current.state.isActive).toBe(true);
       expect(result.current.state.hasUnsavedChanges).toBe(false);
 
-      // 2. Take a snapshot before making changes
+      // 2. Select a section and take a snapshot of it
       act(() => {
-        result.current.actions.takeSnapshot();
+        result.current.actions.takeSnapshot("Some content here.");
       });
 
-      expect(result.current.state.snapshot).toBe("# Original Title\n\nSome content here.");
+      expect(result.current.state.snapshot).toBe("Some content here.");
 
-      // 3. User edits the document
+      // 3. User edits the document (reworks the section)
       act(() => {
-        result.current.actions.setContent("# Better Title\n\nRevised content here.");
+        result.current.actions.setContent("# Original Title\n\nRevised and improved content.");
       });
 
       expect(result.current.state.hasUnsavedChanges).toBe(true);
diff --git a/frontend/src/hooks/usePairWritingState.ts b/frontend/src/hooks/usePairWritingState.ts
index 7e56f7f0..b7192199 100644
--- a/frontend/src/hooks/usePairWritingState.ts
+++ b/frontend/src/hooks/usePairWritingState.ts
@@ -43,8 +43,8 @@ export interface PairWritingActions {
   deactivate: () => void;
   /** Update editor content */
   setContent: (content: string) => void;
-  /** Take a snapshot of current content (REQ-F-23) */
-  takeSnapshot: () => void;
+  /** Take a snapshot of the selected text (REQ-F-23) */
+  takeSnapshot: (selection: string) => void;
   /** Clear the current snapshot */
   clearSnapshot: () => void;
   /** Clear all state (alias for deactivate, used on exit) */
@@ -63,7 +63,7 @@ type PairWritingAction =
   | { type: "ACTIVATE"; content: string }
   | { type: "DEACTIVATE" }
   | { type: "SET_CONTENT"; content: string }
-  | { type: "TAKE_SNAPSHOT" }
+  | { type: "TAKE_SNAPSHOT"; selection: string }
   | { type: "CLEAR_SNAPSHOT" }
   | { type: "MARK_SAVED" }
   | { type: "RELOAD_CONTENT"; content: string };
@@ -109,9 +109,10 @@ function pairWritingReducer(
 
     case "TAKE_SNAPSHOT":
       // REQ-F-24: Only one snapshot at a time; new snapshot replaces previous
+      // Snapshot captures the selected text, not the entire file
       return {
         ...state,
-        snapshot: state.content,
+        snapshot: action.selection,
       };
 
     case "CLEAR_SNAPSHOT":
@@ -186,8 +187,8 @@ export function usePairWritingState(): {
     dispatch({ type: "SET_CONTENT", content });
   }, []);
 
-  const takeSnapshot = useCallback(() => {
-    dispatch({ type: "TAKE_SNAPSHOT" });
+  const takeSnapshot = useCallback((selection: string) => {
+    dispatch({ type: "TAKE_SNAPSHOT", selection });
   }, []);
 
   const clearSnapshot = useCallback(() => {