v0.1 Comments and basic functionality work

docs/DESIGN_REVIEW.md

@@ -0,0 +1,38 @@
+# macOS Design Review
+
+This review checks the current app against Apple's Human Interface Guidelines before a public release.
+
+References:
+
+- Apple HIG overview: https://developer.apple.com/design/human-interface-guidelines
+- Designing for macOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-macos
+- Toolbars: https://developer.apple.com/design/human-interface-guidelines/toolbars
+- Sidebars: https://developer.apple.com/design/human-interface-guidelines/sidebars
+- Menus and the menu bar: https://developer.apple.com/design/human-interface-guidelines/menus and https://developer.apple.com/design/human-interface-guidelines/the-menu-bar
+- Color: https://developer.apple.com/design/human-interface-guidelines/color
+- Typography: https://developer.apple.com/design/human-interface-guidelines/typography
+
+## Result
+
+Status: Pass for the current version 1 implementation direction, with manual visual QA still required on physical Intel and Apple Silicon Macs before a tagged release.
+
+## Checks
+
+- Platform fit: The app is macOS-only, targets macOS 13 or newer, uses SwiftUI/AppKit/PDFKit, and ships as a normal `.app` bundle inside a `.dmg`.
+- Window and toolbar: Primary document controls live in the titlebar toolbar, grouped by opening/sharing, navigation, zoom, annotation, search, and saving.
+- Menus and shortcuts: File, View, and Annotate commands are available through native command menus with standard keyboard shortcuts where appropriate.
+- Sidebars: Page thumbnails, annotation list, and comments review are optional sidebars. The default open-PDF state is single-pane reading, and sidebars open only when requested or restored from user preference.
+- Comments review: The comments sidebar uses a compact review-stream layout with a visible total count, add-comment affordance, collapsible page groups, hidden search/filter controls, and connected reply threads.
+- Color and appearance: The UI uses system colors and materials, so light mode, dark mode, and automatic appearance inherit from macOS.
+- Typography: Text uses system fonts and native SwiftUI controls; no custom brand typography is used in the reading interface.
+- Reading focus: The PDF view remains the central, quiet surface; controls are compact and document-oriented.
+- Accessibility basics: Native controls supply focus states and keyboard access; colors use system palettes with restrained highlight/note colors.
+- Academic workflow: The open, select, highlight, comment, continue reading, save, and share path is available without accounts, sync, projects, or conversion.
+
+## Release QA Still Required
+
+- Run the app on both Apple Silicon and Intel hardware.
+- Verify contrast and focus states in light and dark mode.
+- Verify toolbar and sidebar behavior at narrow and wide window sizes.
+- Verify keyboard-only operation for opening, searching, navigating, annotating, saving, and reviewing comments.
+- Verify VoiceOver labels for toolbar buttons and sidebar controls.

docs/QA.md

@@ -0,0 +1,72 @@
+# Manual PDF Interoperability QA
+
+Run this checklist before tagging a public release.
+
+## Test Files
+
+Use at least:
+
+- A selectable-text journal article.
+- A scanned/image-only course reading.
+- A long PDF near or above 500 pages.
+- A PDF that already contains annotations from Preview or Acrobat.
+- A PDF with bookmarks or an outline.
+
+## App Workflow
+
+1. Open the PDF in I Hate PDFs.
+2. Select text and add a highlight.
+3. Add a comment to the highlight.
+4. Add an underline with a comment.
+5. Select text, right-click, and add a comment from the context menu.
+6. Add free text directly on the page.
+7. Open the comments sidebar and verify count, grouping, search, filters, edit, delete, reply, and click-to-navigate.
+8. Quit and reopen the same PDF at the same approximate window width and verify the app restores that PDF's sidebar state; then open a different PDF and verify it starts in focused single-pane reading unless that document has its own saved state.
+9. Add at least one reply and verify the comments sidebar presents the thread like a clean review/chat stream, with a visible connector line from the parent comment to the reply.
+10. Hover a comment row and verify the corresponding PDF text is highlighted; click both the parent comment text and the reply text in the sidebar and verify the PDF view navigates to and selects the corresponding annotation.
+11. Verify highlights, comment markers, reply icons, and selected sidebar rows use muted native-feeling colors in light mode and do not visually overpower the document.
+12. Switch the app to dark mode and verify the reading background, comments sidebar, editor popover, connector lines, selected rows, text fields, and annotation markers remain legible and restrained.
+13. Save As an annotated copy.
+14. Reopen the annotated copy in I Hate PDFs and verify the annotations and comments remain.
+15. Save over a disposable original and verify the overwrite warning appears.
+
+## External Readers
+
+Before manual reader checks, run the automated PDF structure checks:
+
+```sh
+swift scripts/verify-sample-pdf.swift
+swift scripts/verify-pdf-annotations.swift
+```
+
+These checks generate an annotated PDF, reopen it with PDFKit, and inspect the raw PDF annotation dictionaries for standard `/Highlight`, `/Underline`, `/Text`, `/FreeText`, `/Popup`, `/Contents`, `/QuadPoints`, `/IRT`, `/RT`, and `/Parent` entries.
+
+Open the saved annotated copy in:
+
+- macOS Preview
+- Adobe Acrobat Reader
+- Safari, Chrome, and Firefox PDF viewers where annotations are supported
+
+Verify:
+
+- Highlighted text remains highlighted.
+- Underlined text remains underlined.
+- Selected-text comments remain attached to the referenced text.
+- Highlight and selected-text comments can be opened.
+- Free text remains visible on the page.
+- Existing text, images, layout, bookmarks, and prior annotations remain intact.
+
+## Visual QA Screenshots
+
+Capture current screenshots in `docs/screenshots` for:
+
+- `no-document.png`
+- `default-reading.png`
+- `highlight-comment-popover.png`
+- `selected-text-comment-popover.png`
+- `comments-sidebar.png`, including at least one reply thread with a visible connector line
+- `dark-mode-reading.png`
+
+## Known Version 1 Limitation
+
+PDFKit rejects object-valued `/IRT` reply relationships through its public API. Replies created in this app are saved as visible standard `/Text` annotations, while full cross-reader reply-thread presentation must be verified and improved with a lower-level PDF writer if needed.

docs/screenshots/comments-sidebar.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="920" viewBox="0 0 760 920" role="img" aria-label="I Hate PDFs comments sidebar screenshot">
+  <rect width="760" height="920" fill="#f5f5f7"/>
+  <rect x="80" y="60" width="600" height="800" rx="10" fill="#fbfbfd" stroke="#c9c9ce"/>
+  <text x="118" y="118" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="26" fill="#202124">Comments</text>
+  <text x="118" y="146" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="14" fill="#606166">4 total</text>
+  <rect x="118" y="176" width="524" height="34" rx="7" fill="#ffffff" stroke="#d1d1d6"/>
+  <text x="136" y="198" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="13" fill="#7a7a80">Search comments</text>
+  <rect x="118" y="242" width="524" height="1" fill="#d8d8dd"/>
+  <text x="118" y="282" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="17" font-weight="600" fill="#202124">Page 2</text>
+  <rect x="118" y="306" width="524" height="154" rx="8" fill="#ffffff" stroke="#d5d5da"/>
+  <text x="140" y="344" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="14" font-weight="600" fill="#202124">Highlight</text>
+  <text x="140" y="374" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="13" fill="#606166">Professor</text>
+  <text x="140" y="406" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="15" fill="#202124">This is the core passage for Friday's discussion.</text>
+  <rect x="150" y="480" width="492" height="86" rx="8" fill="#f1f8f8" stroke="#c8dddd"/>
+  <text x="172" y="516" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="13" font-weight="600" fill="#202124">Reply</text>
+  <text x="172" y="546" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="13" fill="#606166">Add this to the lecture notes.</text>
+  <text x="118" y="624" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="17" font-weight="600" fill="#202124">Page 5</text>
+  <rect x="118" y="648" width="524" height="118" rx="8" fill="#ffffff" stroke="#d5d5da"/>
+  <text x="140" y="686" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="14" font-weight="600" fill="#202124">Note</text>
+  <text x="140" y="716" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="13" fill="#606166">Professor</text>
+  <text x="140" y="748" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="15" fill="#202124">Compare this footnote with the appendix.</text>
+</svg>

docs/screenshots/main-window.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="920" viewBox="0 0 1440 920" role="img" aria-label="I Hate PDFs main window screenshot">
+  <rect width="1440" height="920" fill="#f5f5f7"/>
+  <rect x="40" y="40" width="1360" height="840" rx="10" fill="#fbfbfd" stroke="#c9c9ce"/>
+  <rect x="40" y="40" width="1360" height="52" rx="10" fill="#ececf0"/>
+  <circle cx="68" cy="66" r="7" fill="#ff5f57"/>
+  <circle cx="92" cy="66" r="7" fill="#febc2e"/>
+  <circle cx="116" cy="66" r="7" fill="#28c840"/>
+  <rect x="64" y="116" width="210" height="724" fill="#f1f1f4"/>
+  <rect x="308" y="132" width="650" height="692" fill="#ffffff" stroke="#d1d1d6"/>
+  <rect x="358" y="190" width="550" height="14" fill="#d8d8dd"/>
+  <rect x="358" y="228" width="480" height="14" fill="#d8d8dd"/>
+  <rect x="358" y="266" width="520" height="14" fill="#f7dc55" opacity="0.75"/>
+  <rect x="358" y="304" width="470" height="14" fill="#d8d8dd"/>
+  <rect x="358" y="342" width="510" height="14" fill="#d8d8dd"/>
+  <rect x="996" y="116" width="364" height="724" fill="#f7f7f9"/>
+  <text x="1020" y="158" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="24" fill="#202124">Comments</text>
+  <rect x="1020" y="190" width="316" height="118" rx="8" fill="#ffffff" stroke="#d5d5da"/>
+  <text x="1040" y="226" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="15" fill="#202124">Highlight</text>
+  <text x="1040" y="254" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="13" fill="#606166">Discuss this claim in class.</text>
+  <rect x="1020" y="326" width="316" height="118" rx="8" fill="#ffffff" stroke="#d5d5da"/>
+  <text x="1040" y="362" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="15" fill="#202124">Note</text>
+  <text x="1040" y="390" font-family="-apple-system, BlinkMacSystemFont, sans-serif" font-size="13" fill="#606166">Connect to the seminar reading.</text>
+</svg>