Clean up repository structure and release docs
This commit is contained in:
Akshay Kolli
@@ -1,60 +0,0 @@
|
||||
# Mac App Store Release
|
||||
|
||||
Bundle ID: `net.akkolli.ihatepdfs`
|
||||
|
||||
Current App Store build values:
|
||||
|
||||
- `CFBundleShortVersionString`: `0.4.0`
|
||||
- `CFBundleVersion`: `6`
|
||||
- Privacy policy URL: `https://www.akkolli.net/ihatepdfs/privacy`
|
||||
- Marketing/support URL: `https://www.akkolli.net/ihatepdfs`
|
||||
|
||||
Paste-ready metadata, review notes, privacy answers, and screenshot guidance live in `docs/APP_STORE_COPY.md`.
|
||||
The general release checklist is in `docs/RELEASE.md`.
|
||||
|
||||
## Required Apple Developer Items
|
||||
|
||||
- An explicit macOS App ID for `net.akkolli.ihatepdfs`.
|
||||
- An App Store provisioning profile for that App ID.
|
||||
- An application signing certificate installed in Keychain, usually named `Apple Distribution: ...` or `3rd Party Mac Developer Application: ...`.
|
||||
- An installer signing certificate installed in Keychain, usually named `3rd Party Mac Developer Installer: ...`. Apple may label this certificate type as Mac Installer Distribution in the developer portal or Xcode.
|
||||
|
||||
The app only needs these sandbox entitlements right now:
|
||||
|
||||
- `com.apple.security.app-sandbox`
|
||||
- `com.apple.security.files.user-selected.read-write`
|
||||
|
||||
Do not add network, Apple Events, Downloads-folder, or bookmark entitlements unless the app gains a feature that requires them.
|
||||
|
||||
## Build The Upload Package
|
||||
|
||||
Download the App Store provisioning profile from Apple Developer, then run:
|
||||
|
||||
```sh
|
||||
APP_SIGNING_IDENTITY="3rd Party Mac Developer Application: Your Name (TEAMID)" \
|
||||
INSTALLER_SIGNING_IDENTITY="3rd Party Mac Developer Installer: Your Name (TEAMID)" \
|
||||
PROVISIONING_PROFILE="$HOME/Downloads/IHatePDFs_AppStore.provisionprofile" \
|
||||
scripts/make-app-store-pkg.sh
|
||||
```
|
||||
|
||||
The package is written to `dist/IHatePDFs-v0.4-macos-appstore.pkg`.
|
||||
|
||||
The script derives the App Store application identifier and team identifier from the provisioning profile before signing. It builds the App Store app in a temporary staging directory, so the direct-download `dist/I Hate PDFs.app` remains a clean app bundle without an embedded provisioning profile. It also clears download quarantine metadata from the staged bundle before packaging, because App Store Connect rejects packages that contain quarantine extended attributes.
|
||||
|
||||
If macOS opens a Keychain private-key access prompt during `codesign`, approve it, preferably with Always Allow for the selected signing certificate, and rerun the command. The build cannot finish unattended until the private key for the selected application signing certificate is allowed.
|
||||
|
||||
Before uploading, verify that the package matches the current build number:
|
||||
|
||||
```sh
|
||||
REQUIRE_APP_STORE_PKG=1 scripts/verify-release-artifacts.sh
|
||||
```
|
||||
|
||||
This catches stale package files, bundle-ID mismatches, missing embedded provisioning profiles, missing sandbox/user-selected-file entitlements, and app/package version mismatches.
|
||||
|
||||
Use `pkgutil --check-signature` and App Store Connect or Transporter validation for this App Store package. A local `spctl -t install` assessment is a Developer ID distribution check and may reject a package signed with the Mac App Store `3rd Party Mac Developer Installer` identity even when the package signature is valid for App Store upload.
|
||||
|
||||
## Upload
|
||||
|
||||
Upload the `.pkg` with Transporter. You can also set `VALIDATE_WITH_ALTOOL=1` when running `scripts/make-app-store-pkg.sh` if you want the script to perform an `altool` validation after packaging. After App Store Connect processes the build, select it in the app version, finish metadata, answer App Privacy, fill review notes, and submit for review.
|
||||
|
||||
Keep `CFBundleShortVersionString` as `0.4.0` and `CFBundleVersion` as `6` for the next upload. Increment `BUILD_NUMBER` in `scripts/release-version.sh` before uploading another build for the same version.
|
||||
@@ -1,97 +0,0 @@
|
||||
# App Store Copy
|
||||
|
||||
Use this as the source of truth when filling out App Store Connect for `net.akkolli.ihatepdfs`.
|
||||
|
||||
## URLs
|
||||
|
||||
- Marketing URL: `https://www.akkolli.net/ihatepdfs`
|
||||
- Support URL: `https://www.akkolli.net/ihatepdfs`
|
||||
- Privacy Policy URL: `https://www.akkolli.net/ihatepdfs/privacy`
|
||||
|
||||
## Copyright
|
||||
|
||||
`2026 Akshay Kolli`
|
||||
|
||||
## App Information
|
||||
|
||||
- Name: `I Hate PDFs`
|
||||
- Subtitle: `A small PDF review app`
|
||||
- Category: `Productivity`
|
||||
- Secondary category: `Education`
|
||||
|
||||
## Promotional Text
|
||||
|
||||
Read, highlight, comment, and review local PDFs without accounts, cloud upload, or heavyweight document management.
|
||||
|
||||
## Description
|
||||
|
||||
I Hate PDFs is a small native macOS app for reading and reviewing local PDF files.
|
||||
|
||||
Open a PDF, highlight important text, add comments, write free-text notes, and review everything from a compact comments sidebar. The app writes standard PDF annotations so your saved files can be opened in common PDF readers like Preview and Adobe Acrobat.
|
||||
|
||||
The app is intentionally lightweight. It uses native macOS document behavior, keeps your PDFs on your Mac, and does not require an account.
|
||||
|
||||
Features:
|
||||
|
||||
- Open local PDF files from disk, Finder, drag and drop, or recent documents.
|
||||
- Read with native PDFKit scrolling, zoom, fit-to-width, fit-to-page, page navigation, and search.
|
||||
- Highlight selected text without opening an unnecessary comment box.
|
||||
- Add selected-text comments, underline comments, and free-text notes.
|
||||
- Press Return to save comments and Shift-Return to insert a new line.
|
||||
- Review annotations in a comments sidebar with search, filters, replies, edit, delete, and click-to-navigate.
|
||||
- Customize highlight and comment colors from Settings.
|
||||
- Save annotations directly into a PDF after an overwrite warning, or use Save As for a separate annotated copy.
|
||||
- Share the saved PDF through the native macOS share sheet.
|
||||
|
||||
Privacy:
|
||||
|
||||
I Hate PDFs does not collect analytics, does not require sign-in, and does not upload your documents. Your PDFs stay on your Mac unless you choose to share them.
|
||||
|
||||
## Keywords
|
||||
|
||||
pdf,reader,annotate,highlight,comments,review,professor,academic,documents,notes
|
||||
|
||||
## What's New
|
||||
|
||||
Keeps the app focused on fast local PDF reading and annotation, with recent PDFs, focused open behavior, sidebar polish, bookmarks, highlight sorting, and Settings for annotation colors.
|
||||
|
||||
## App Review Notes
|
||||
|
||||
I Hate PDFs is a local macOS PDF reader and annotation utility.
|
||||
|
||||
No account is required. The reviewer can test with any local `.pdf` file. The app asks for user-selected file access only when opening, saving, or sharing a PDF.
|
||||
|
||||
Suggested review path:
|
||||
|
||||
1. Launch the app.
|
||||
2. Open or drag in any PDF.
|
||||
3. Select text and add a highlight or comment.
|
||||
4. Open the comments sidebar to review annotations.
|
||||
5. Save As to create an annotated copy.
|
||||
6. Open Settings with Command-, or File > Settings... to change annotation colors.
|
||||
7. Open Bookmarks and Highlights from the sidebar controls to verify the review views.
|
||||
|
||||
## App Privacy Answers
|
||||
|
||||
Recommended App Privacy summary:
|
||||
|
||||
- Data collection: no data collected.
|
||||
- Tracking: no tracking.
|
||||
- Third-party advertising: no.
|
||||
- User account required: no.
|
||||
|
||||
The app works with user-selected local PDF files. It does not transmit documents to a server and does not include analytics.
|
||||
|
||||
## Screenshot Checklist
|
||||
|
||||
Use real bitmap screenshots, not drawn SVG mockups.
|
||||
|
||||
Required minimum set:
|
||||
|
||||
- Empty window with the Open PDF action and compact Recent PDFs area.
|
||||
- Main reading view with a PDF page dominant.
|
||||
- Highlight or comment editor popover on selected text.
|
||||
- Comments sidebar with several annotations and at least one reply.
|
||||
- Settings window showing color controls.
|
||||
|
||||
Capture light-mode screenshots first. Add dark-mode screenshots if they make the product quality clearer.
|
||||
@@ -1,39 +0,0 @@
|
||||
# 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.
|
||||
- Responsive layout: Compact windows use a compact toolbar/status treatment and keep sidebars mutually exclusive; regular and wide windows can show both sidebars while preserving a usable PDF reading width.
|
||||
- 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 compact, regular, 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.
|
||||
@@ -1,72 +0,0 @@
|
||||
# Engineering Principles
|
||||
|
||||
I Hate PDFs is intentionally a small native macOS app. Future work should preserve that constraint unless there is a documented, user-visible reason to do otherwise.
|
||||
|
||||
## Native First
|
||||
|
||||
- Build features with Swift, SwiftUI, AppKit, PDFKit, and other system frameworks that ship with macOS.
|
||||
- Do not replace the app with Electron, Chromium, a web runtime, a bundled JavaScript app shell, or a cross-platform UI toolkit.
|
||||
- Do not bundle a PDF renderer, OCR engine, database, scripting runtime, or large framework when a macOS system API can satisfy the requirement.
|
||||
- Prefer native macOS controls and document behaviors over custom reimplementations when they meet the product need.
|
||||
|
||||
## Small By Default
|
||||
|
||||
Every change should aim for the smallest final app that still delivers the required fluidity, reliability, and functionality.
|
||||
|
||||
- Keep third-party dependencies at or near zero. Any new package must justify its shipped size, runtime cost, maintenance cost, and why system APIs are insufficient.
|
||||
- Keep assets minimal. Avoid large raster images, fonts, sample PDFs, videos, model files, or generated resources in the app bundle.
|
||||
- Keep build outputs out of source and releases unless they are intentional release artifacts.
|
||||
- Prefer dynamic links to Apple system frameworks over vendored libraries.
|
||||
- Avoid storing duplicate PDF data, rendered page caches, or annotation indexes unless profiling shows they are required for fluid interaction.
|
||||
- Favor targeted updates over whole-document rescans for common interactions such as editing, replying, filtering, hovering, and sidebar refreshes.
|
||||
|
||||
## Size Budget
|
||||
|
||||
The release DMG should stay as small as practical. Treat size growth as a product regression, not just a packaging detail.
|
||||
|
||||
Hard release-size budget: each direct-download per-architecture installer must be under 400 KB, measured as fewer than 400,000 bytes. Universal builds may be larger, but they do not satisfy the small-download budget. Run `scripts/make-tiny-archives.sh` before release; it builds and checks `IHatePDFs-v<version>-macos-arm64.tar.xz` and `IHatePDFs-v<version>-macos-x86_64.tar.xz` by default.
|
||||
|
||||
Before merging release-impacting work, compare:
|
||||
|
||||
```sh
|
||||
scripts/build-app.sh
|
||||
scripts/make-dmg.sh
|
||||
du -sh "dist/I Hate PDFs.app" \
|
||||
"dist/I Hate PDFs.app/Contents/MacOS/IHatePDFs" \
|
||||
"dist/I Hate PDFs.app/Contents/Resources/AppIcon.icns" \
|
||||
dist/IHatePDFs-v*-macos.dmg
|
||||
```
|
||||
|
||||
If a change materially increases the app bundle or DMG size, document why in the PR or commit notes. A useful rule of thumb: any dependency addition, bundled asset addition, or release-size increase above roughly 10% needs explicit justification.
|
||||
|
||||
## Performance Budget
|
||||
|
||||
Small size should not come at the expense of reader fluidity.
|
||||
|
||||
- Opening, scrolling, zooming, searching, annotating, saving, and sidebar navigation should remain responsive on long PDFs.
|
||||
- Optimize around measured user workflows instead of speculative micro-optimizations.
|
||||
- Keep expensive work page-scoped or lazy when possible.
|
||||
- Use `swift test` plus the PDF verification scripts after behavior changes:
|
||||
|
||||
```sh
|
||||
swift test
|
||||
swift scripts/verify-sample-pdf.swift
|
||||
swift scripts/verify-pdf-annotations.swift
|
||||
```
|
||||
|
||||
## Release Packaging
|
||||
|
||||
Release builds should use the existing lightweight packaging path:
|
||||
|
||||
```sh
|
||||
scripts/build-app.sh
|
||||
scripts/make-dmg.sh
|
||||
```
|
||||
|
||||
`scripts/build-app.sh` strips release binaries by default to reduce shipped size. Use `STRIP_RELEASE=0 scripts/build-app.sh` only when a symbol-rich release build is needed for debugging.
|
||||
|
||||
Universal `arm64` + `x86_64` builds are the default for public releases. Single-architecture builds are acceptable for local testing:
|
||||
|
||||
```sh
|
||||
ARCHS="" scripts/build-app.sh
|
||||
```
|
||||
@@ -1,35 +0,0 @@
|
||||
# Functionality Audit
|
||||
|
||||
Date: 2026-06-29
|
||||
|
||||
## Current Build Scope
|
||||
|
||||
I Hate PDFs v0.4 is a small native macOS PDF reader and annotation app. The shipping scope is:
|
||||
|
||||
- Local PDF opening, recent documents, drag/drop, close-current-PDF, and focused reader startup.
|
||||
- PDFKit reading, page navigation, zoom, fit controls, search, and responsive sidebars.
|
||||
- Highlights, underline comments, selected-text comments, free text, replies, review state, filters, grouped comments, bookmarks, and highlight sorting.
|
||||
- Settings for highlight and comment colors.
|
||||
- Save, Save As, native Share, overwrite warnings, unsent reply-draft warnings, and empty temporary annotation cleanup.
|
||||
- Lightweight release packaging with `.app`, `.dmg`, tiny per-architecture archives, and App Store package scripts.
|
||||
|
||||
## Removed Scope
|
||||
|
||||
The experimental Fill & Sign and PDF signing work has been removed from source, tests, scripts, settings, menus, and release docs for v0.4. This includes custom flat fill marks, form-field scanning/navigation, form choice editing, Keychain-backed PDF signing, signature validation/inspection, and signed-document save branching.
|
||||
|
||||
## Verification
|
||||
|
||||
Run before release:
|
||||
|
||||
```sh
|
||||
swift build
|
||||
swift test
|
||||
swift scripts/verify-sample-pdf.swift
|
||||
swift scripts/verify-pdf-annotations.swift
|
||||
scripts/build-app.sh
|
||||
scripts/make-dmg.sh
|
||||
scripts/make-tiny-archives.sh
|
||||
scripts/verify-release-artifacts.sh
|
||||
```
|
||||
|
||||
Manual QA remains documented in `docs/QA.md`.
|
||||
26
docs/QA.md
26
docs/QA.md
@@ -2,6 +2,18 @@
|
||||
|
||||
Run this checklist before tagging a public release.
|
||||
|
||||
## Workflow Contract
|
||||
|
||||
Use this section as the source of truth when checking whether a feature matches the product workflow before changing or releasing it.
|
||||
|
||||
- Opened PDFs intentionally reset to focused single-pane reading with sidebars hidden.
|
||||
- Plain Highlight is standalone.
|
||||
- Selected-text Comment and Underline open the anchored editor.
|
||||
- The visible Save toolbar icon is intentionally absent. Save remains available from the File menu and keyboard shortcut; Share remains visible.
|
||||
- Compact windows intentionally make left and right sidebars mutually exclusive to preserve usable PDF width.
|
||||
- Sidebar resize handles should be easy to grab through hover/cursor affordance without becoming large visual dividers.
|
||||
- Experimental Fill & Sign, custom form-field navigation, PDF signing, signature inspection, and related QA are outside v0.4 scope.
|
||||
|
||||
## Latest v0.4 Automated QA Run
|
||||
|
||||
Completed on 2026-06-29:
|
||||
@@ -12,7 +24,6 @@ Completed on 2026-06-29:
|
||||
Before release, also run:
|
||||
|
||||
```sh
|
||||
swift scripts/verify-sample-pdf.swift
|
||||
swift scripts/verify-pdf-annotations.swift
|
||||
swift build -c release --product IHatePDFs
|
||||
scripts/build-app.sh
|
||||
@@ -64,15 +75,24 @@ Use at least:
|
||||
29. Start typing a sidebar reply without sending it, then close, replace, save, or share the PDF and verify the app warns before omitting or discarding the draft.
|
||||
30. Create a new selected-text comment or free text, leave its popover empty, choose Save or Share, and verify the temporary empty annotation is discarded.
|
||||
|
||||
## Regression Coverage
|
||||
|
||||
- Focused reading layout after opening a PDF.
|
||||
- Returning to the empty-window workflow after closing a PDF.
|
||||
- Compact one-sidebar-at-a-time behavior.
|
||||
- Page sidebar toggle closing the active Marks sidebar instead of switching to Pages first.
|
||||
- Right-sidebar toolbar toggle closing and reopening the current right mode without switching tabs.
|
||||
- Regular-width ability to show navigation and review sidebars together.
|
||||
- Save availability for clean, dirty, and reply-draft-only states.
|
||||
|
||||
## 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 raw PDF annotation dictionaries for standard `/Highlight`, `/Underline`, `/Text`, `/FreeText`, `/Contents`, `/QuadPoints`, `/IRT`, `/RT`, and `/Parent` entries.
|
||||
This check generates an annotated PDF, reopens it with PDFKit, and inspects raw PDF annotation dictionaries for standard `/Highlight`, `/Underline`, `/Text`, `/FreeText`, `/Contents`, `/QuadPoints`, `/IRT`, `/RT`, and `/Parent` entries.
|
||||
|
||||
For Preview, Acrobat Reader, and browser PDF viewers, verify exported markup comments keep their comment text on the parent annotation's standard `/Contents` key and do not depend on PDFKit-generated `/Popup` links for highlights or underlines.
|
||||
|
||||
@@ -23,7 +23,6 @@ Run these before tagging or uploading:
|
||||
|
||||
```sh
|
||||
swift test
|
||||
swift scripts/verify-sample-pdf.swift
|
||||
swift scripts/verify-pdf-annotations.swift
|
||||
scripts/build-app.sh
|
||||
BUILD_APP=0 scripts/make-dmg.sh
|
||||
@@ -34,13 +33,6 @@ scripts/verify-release-artifacts.sh
|
||||
`scripts/make-tiny-archives.sh` builds per-architecture direct-download archives and
|
||||
fails if either archive is `>= 400,000` bytes.
|
||||
|
||||
For signature changes, also run:
|
||||
|
||||
```sh
|
||||
USE_TEMP_SIGNING_KEYCHAIN=1 scripts/verify-pdf-signatures.sh
|
||||
scripts/prepare-acrobat-qa.sh
|
||||
```
|
||||
|
||||
Finish the manual reader checks in `docs/QA.md` before public distribution.
|
||||
|
||||
## Direct Download
|
||||
@@ -57,12 +49,39 @@ pollute source control.
|
||||
|
||||
## App Store
|
||||
|
||||
Use `docs/APP_STORE.md` for signing identities, provisioning profile setup, and the
|
||||
upload package command. After building the App Store package, run:
|
||||
Bundle ID: `net.akkolli.ihatepdfs`
|
||||
|
||||
Project website: `https://www.akkolli.net/ihatepdfs`
|
||||
|
||||
Support email: `akshaykolli@hotmail.com`
|
||||
|
||||
Required Apple Developer items:
|
||||
|
||||
- Explicit macOS App ID for `net.akkolli.ihatepdfs`.
|
||||
- App Store provisioning profile for that App ID.
|
||||
- Application signing certificate installed in Keychain.
|
||||
- Installer signing certificate installed in Keychain.
|
||||
|
||||
The app only needs these sandbox entitlements right now:
|
||||
|
||||
- `com.apple.security.app-sandbox`
|
||||
- `com.apple.security.files.user-selected.read-write`
|
||||
|
||||
Do not add network, Apple Events, Downloads-folder, or bookmark entitlements unless a shipped feature requires them.
|
||||
|
||||
Build the upload package:
|
||||
|
||||
```sh
|
||||
APP_SIGNING_IDENTITY="3rd Party Mac Developer Application: Your Name (TEAMID)" \
|
||||
INSTALLER_SIGNING_IDENTITY="3rd Party Mac Developer Installer: Your Name (TEAMID)" \
|
||||
PROVISIONING_PROFILE="$HOME/Downloads/IHatePDFs_AppStore.provisionprofile" \
|
||||
scripts/make-app-store-pkg.sh
|
||||
```
|
||||
|
||||
After building the App Store package, run:
|
||||
|
||||
```sh
|
||||
REQUIRE_APP_STORE_PKG=1 scripts/verify-release-artifacts.sh
|
||||
```
|
||||
|
||||
Do not change App Store entitlements unless a shipped feature requires the new
|
||||
capability.
|
||||
Upload the `.pkg` with Transporter or App Store Connect tooling. Keep `APP_VERSION` and `BUILD_NUMBER` in `scripts/release-version.sh` aligned with App Store Connect before submitting.
|
||||
|
||||
@@ -1,53 +0,0 @@
|
||||
# Workflow Audit
|
||||
|
||||
Date: 2026-06-29
|
||||
|
||||
This file records the intended v0.4 user flow. It is the source of truth when checking whether a feature matches the product workflow before changing or releasing it.
|
||||
|
||||
## Current Capabilities
|
||||
|
||||
1. Open local PDFs from an open panel, drag/drop, recent documents, and file URLs.
|
||||
2. Start each opened PDF in focused reading: sidebars hidden, PDF fit to available width, previous document sidebar state ignored.
|
||||
3. Read with PDFKit scrolling, page navigation, zoom, fit width, fit page, two-page continuous view, and search.
|
||||
4. Use a responsive layout across compact, regular, and wide Mac windows.
|
||||
5. Use the left sidebar for page thumbnails and annotation marks.
|
||||
6. Use the right sidebar for Comments, Highlights, and Bookmarks; the right-sidebar toolbar button is a visibility toggle for the active right mode.
|
||||
7. Highlight selected text, use highlighter mode, and choose highlight colors.
|
||||
8. Add selected-text comments, underline comments, and free-text annotations.
|
||||
9. Use PDF-view shortcuts `H`, `U`, and `C` without conflicting with Command-C.
|
||||
10. Edit/delete annotations and comment threads through anchored popovers and sidebar controls.
|
||||
11. Review comments with search, filters, page grouping, collapsed groups, review state, replies, hover highlighting, edit/delete, and navigation.
|
||||
12. Review highlights sorted by color or page.
|
||||
13. Add, remove, and navigate per-document bookmarks.
|
||||
14. Configure highlight and comment colors in Settings.
|
||||
15. Save, Save As, Share, warn for unsent reply drafts, discard empty temporary editors, and warn before overwriting originals.
|
||||
16. Package a small native app through the release scripts, DMG script, tiny archive script, and App Store package script.
|
||||
|
||||
## Removed From v0.4
|
||||
|
||||
The experimental Fill & Sign, custom form-field navigation, form choice popover, PDF signing, signature inspection, signed-document save safeguards, signature QA scripts, and related tests were removed from v0.4. Revisit that work later as a smaller design from scratch.
|
||||
|
||||
## Workflow Decisions
|
||||
|
||||
- Opened PDFs intentionally reset to focused single-pane reading with sidebars hidden. Opening a PDF should maximize the reading area and leave comments, highlights, bookmarks, page thumbnails, and annotation marks closed until the user asks for them.
|
||||
- Plain Highlight is standalone. Selected-text Comment and Underline open the anchored editor.
|
||||
- The visible Save toolbar icon is intentionally absent. Save remains available from the File menu and keyboard shortcut; Share remains visible.
|
||||
- Compact windows intentionally make left and right sidebars mutually exclusive to preserve usable PDF width.
|
||||
- Sidebar resize handles should be easy to grab through hover/cursor affordance without becoming large visual dividers.
|
||||
|
||||
## Regression Coverage
|
||||
|
||||
- Focused reading layout after opening a PDF.
|
||||
- Returning to the empty-window workflow after closing a PDF.
|
||||
- Compact one-sidebar-at-a-time behavior.
|
||||
- Page sidebar toggle closing the active Marks sidebar instead of switching to Pages first.
|
||||
- Right-sidebar toolbar toggle closing and reopening the current right mode without switching tabs.
|
||||
- Regular-width ability to show navigation and review sidebars together.
|
||||
- Save availability for clean, dirty, and reply-draft-only states.
|
||||
|
||||
## Manual QA Gaps
|
||||
|
||||
- Real Finder drag/drop, menu disabled states, visual Settings interaction, alert button flows, native share picker, popover text focus, and sidebar resize affordances need UI automation or manual QA.
|
||||
- Preview, Acrobat Reader, and browser PDF-viewer checks remain external interoperability gates even though raw PDF structure checks exist.
|
||||
- Cross-reader reply-thread display is not fully proven because PDFKit public APIs do not provide reliable object-valued `/IRT` writing. Primary annotation comments remain standard `/Contents`.
|
||||
- Screenshot docs still need recapture before public marketing or release use.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 519 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 797 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 498 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 44 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 496 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 756 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 522 KiB |
Reference in New Issue
Block a user