FountainEditorKit.git · PLANS.md

revision 5b289641fc57ec5e8e8aa8dec3d6b32f49b98a75 · complete file
# PLANS.md

This file defines the intent protocol for multi-step or high-risk work in this repository.

## When a Plan Is Required
Create or update a plan before changes when work is:
- Multi-step (more than a small, single-file fix).
- Cross-cutting (touches public API + parsing + UI).
- High-risk (API breaking changes, behavior changes in the editor surface, or CI/release changes).
- Safety sensitive (data loss / truncation / persistence regressions).

## Plan Format (Template)
Use this structure and keep it concise:

Title:
Goal:
Scope:
Non-goals:
Constraints:
Risks:
Plan:
- Step 1 (status: pending | in_progress | done) - intent
- Step 2 (status: pending | in_progress | done) - intent
Validation:
- How you will confirm success (tests, checks, manual steps)

## Acceptance Criteria
- The plan states intent and scope clearly.
- Steps are minimal and ordered.
- Validation is explicit and feasible.
- Any deviations are recorded and justified.

---

Title: FountainEditorKit v0.1 (framework-level editor surface)
Goal: Provide a reusable, framework-level Fountain editor (`FountainEditor`) that is stable under long text, deterministic in parsing/highlighting, and safe (no text loss/truncation).
Scope: Fountain parsing (line kinds, outline), syntax highlighting, a SwiftUI/AppKit editor component, and a focused test suite + CI.
Non-goals: A full IDE (git integration, multi-file workspaces), rich formatting, or storing/deriving “meaning” from the text.
Constraints: No third-party dependencies; deterministic tests; editor must preserve raw text exactly; macOS 14 target.
Risks: UI component tests can be flaky; mitigate by testing core logic heavily and keeping UI tests small + main-thread only.
Plan:
- Step 1 (status: done) - Implement deterministic Fountain line classifier + outline extraction utilities.
- Step 2 (status: done) - Implement syntax highlighter over `NSTextStorage` with a configurable theme.
- Step 3 (status: done) - Implement `FountainEditor` (SwiftUI wrapper over `NSTextView`) with safe binding updates (no lost edits).
- Step 4 (status: done) - Add unit tests for classifier, outline, search/replace helpers, and highlighter attribute application.
- Step 5 (status: done) - Add a minimal UI binding test to ensure `NSTextView` edits propagate to bindings.
- Step 6 (status: done) - Add GitHub Actions CI and README badge; run `swift test`.
Validation:
- `swift test`
- Manual: open a demo host app (downstream) and edit a multi-page script; confirm no laggy truncation and that undo/redo works.