Gingerwrite

A native macOS app for writing novels and becoming a better writer.

Gingerwrite provides a quiet place to write, organize a manuscript into acts and chapters, check spelling, and work toward a realistic word-count deadline. Over time, it will help writers understand their prose through detailed, local analysis.

The writer writes the book. Gingerwrite will never generate prose, continue a scene, rewrite a paragraph, or imitate another writer. Future machine learning will identify patterns and explain potential improvements while leaving creative decisions with the author.

M0–M3 are implemented as a runnable local development build. The app includes manuscript organization, native writing and autosave, backup/recovery, plain-text export, appearance preferences, and adaptive writing goals. M4 release qualification, signing, and notarization remain outstanding. See verification evidence and limitations.

First release

Area	Implemented experience
Manuscript organization	Create novels with ordered acts and chapters. Rename, reorder, and move chapters between acts.
Writing	Write one chapter at a time in a responsive native editor with undo/redo, selection, copy/paste, find, and reliable autosave.
Spelling	Use native macOS spelling checks, with suggestions and ignore/learn controls. Corrections remain the writer's choice.
Writing goals	Set a final manuscript word count and finish date. See current progress, words remaining, and the required daily pace, recalculated when writing or missing days.
Appearance	A beautiful, minimal interface with light, dark, and system appearance. Use DM Mono for the manuscript and app-controlled UI text.
Local storage	Keep manuscripts and goals in SQLite on the Mac. Writing must work without an account, server, or internet connection.
Ownership and recovery	Reopen safely after quitting, make recoverable backups, and export a manuscript as plain text.

The initial editor stores plain text. Rich formatting, scenes, character databases, collaboration, cloud sync, and publishing layouts are outside the first release.

Writing goals that adapt

A goal means finish with a total of X manuscript words by date Y. Existing words count toward the target.

words_remaining = max(0, target_words - current_manuscript_words)
required_daily_pace = ceil(words_remaining / remaining_calendar_days)

Remaining days include today and the deadline date, measured in the novel's selected time zone. For example, 20,000 words remaining over 10 days means 2,000 words per day. After a missed day, 20,000 words over 9 days becomes 2,223 words per day.

The pace updates as the manuscript changes. A completed goal shows zero remaining; an unfinished goal past its deadline shows an overdue state and invites a new deadline. Titles do not count toward the manuscript total. The detailed rules and edge cases are specified in PLAN.md.

Product principles

• Protect the manuscript. Saving, recovery, and export are core functionality.
• Keep writing comfortable. Typography, spacing, keyboard behavior, and responsiveness matter more than adding controls.
• Stay native. Build a macOS application with native controls and text editing.
• Keep the writer in control. Feedback is optional, explainable, dismissible, and never silently changes prose.
• Keep manuscript data local. Future analysis should run on the device. Manuscripts are not telemetry or training data.
• Build incrementally. Start with a small application and introduce analysis infrastructure when a real feature needs it.

Technical direction

Concern	Implementation
Application	Swift and SwiftUI for the window, navigation, settings, and supporting views.
Editor	AppKit NSTextView, hosted in SwiftUI using NSViewRepresentable, for native text editing and spelling integration.
Persistence	SQLite with explicit migrations, transactions, and a small persistence layer.
Core logic	Plain Swift types for manuscript structure, word counts, and goal calculations.
Typography	Bundle DM Mono and its license so the font is available offline. Preserve native system dialogs and provide glyph fallback where needed.
Future analysis	Deterministic rules first; evaluate Apple's Natural Language and Core ML for local linguistic processing and non-generative models.

These decisions are implemented in the application. Apple's text-view documentation and SwiftUI AppKit integration API support the proposed editor approach. DM Mono is available from its upstream font repository.

Chapter text remains authoritative. Future paragraph, sentence, token, and text-span analysis will be derived from identified revisions of that text. This allows granular findings without making a database row for every word the foundation of the editor.

macOS is the only initial platform. Keep text and domain logic independent of UI frameworks where practical, but do not build a cross-platform UI or compatibility layer before another platform is needed.

Future direction

After the writing experience is dependable, add capabilities in this order:

1. Granular paragraph, sentence, token, and range analysis with reliable highlighting.
2. Grammar and usage checks, with explanations and explicit acceptance of local corrections.
3. Active/passive voice identification, repetition, sentence structure, and prose statistics.
4. A thesaurus with definitions, sense distinctions, and deliberate word replacement.
5. Local machine learning for descriptive style analysis and useful, evidence-based suggestions.

Intelligent suggestions mean observations such as “this paragraph repeats this word” or “this sentence may use passive voice,” with the relevant passage highlighted. They do not mean generated replacements. Style feedback should respect dialogue, dialect, genre, and intentional rule-breaking.

Roadmap and development

PLAN.md contains the architecture, data model, goal rules, milestones, acceptance criteria, testing strategy, and documentation schedule.

Build, run, and test

Requires macOS 15 or newer. Verified with Xcode 26.6 and Swift 6.3.3 on an M3 MacBook Air running macOS 26.5.1. The Xcode project builds both Apple Silicon and Intel; Intel/macOS 15 runtime validation is still pending the release matrix. There are no external code dependencies or network setup steps.

xcodebuild -project Gingerwrite.xcodeproj -scheme Gingerwrite \
  -configuration Debug -derivedDataPath build CODE_SIGNING_ALLOWED=NO build
open build/Build/Products/Debug/Gingerwrite.app
xcodebuild -project Gingerwrite.xcodeproj -scheme Gingerwrite \
  -destination 'platform=macOS,arch=arm64' -derivedDataPath build \
  CODE_SIGNING_ALLOWED=NO test

On Intel, change the test destination to arch=x86_64. You can also open Gingerwrite.xcodeproj and run the shared Gingerwrite scheme. The unsigned development build is for local use, not distribution.

A command-line alternative for the same test sources:

swift test

When running inside a restricted agent sandbox, use repository-local module caches:

CLANG_MODULE_CACHE_PATH="$PWD/.build/ModuleCache" \
SWIFTPM_MODULECACHE_OVERRIDE="$PWD/.build/ModuleCache" \
swift test --disable-sandbox

After adding Swift files, regenerate the checked-in Xcode project with python3 scripts/generate-project.py. Normal builds do not require generation.

Start with the user guide, writing goals, architecture, and data ownership/recovery.

The first release is ready when someone can create a novel, organize it, write comfortably, check spelling, follow an adaptive goal, quit and reopen without losing saved work, and export or recover their manuscript entirely offline.

Source formatting

Use four spaces for indentation and the checked-in .swift-format rules for Swift sources and tests. .editorconfig records whitespace conventions for other text files.

./scripts/format.sh          # Format Swift sources and tests.
./scripts/format.sh --check  # Check formatting without changing files.
./scripts/verify.sh          # Check formatting, run tests, and build the app.

The project generator emits readable Xcode project and scheme files. Edit scripts/generate-project.py and regenerate those files instead of formatting generated output by hand.