FountainEditorKit.git · PLANS.md

revision 02bb5ddf56beec015d5c3fe77253441c03b5e3a8 · 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.

---

Title: FountainEditorKit v0.2 — namespaced presentation extensions
Goal: Let Fountain-based copilots encode durable, attractive, accessible presentation cards inside valid Fountain notes without flattening evidence, consent, or retrieval provenance into log text.
Scope: A deterministic `[[fountain:presentation … ]]` extension parser/encoder, public presentation models, a reusable SwiftUI presentation view, tests, documentation, changelog, and a downstream Modernization Studio smoke.
Non-goals: Interpreting free-form prose, changing standard Fountain screenplay classification, fetching sources, deciding consent, or replacing the downstream application's domain models.
Constraints: Preserve source text exactly; extension recognition is an explicit machine grammar; malformed or unknown extensions remain ordinary Fountain notes; parsing is deterministic and offline; no third-party dependencies; all visible content and disclosure controls are exposed through accessibility.
Risks: A structured card could hide provenance or make a decision look more authoritative than its evidence. Mitigate by keeping the concise finding and full retrieval record in the same document, rendering source/revision prominently, and placing raw receipts in an accessible disclosure rather than dropping them.
Plan:
- Step 1 (status: completed) - Added the namespaced extension block parser and versioned presentation document model/codec.
- Step 2 (status: completed) - Added a reusable SwiftUI card for summary, status, facts, quotations, sources, timeline, receipts, and requested replies with FCIS-AX semantics.
- Step 3 (status: completed) - Added deterministic parser/codec tests, complete plain-text fallbacks, and public usage documentation.
- Step 4 (status: completed) - Integrated the API into Modernization Studio's Chapter 32 Copilot path and removed raw-ledger presentation from the visible transcript.
- Step 5 (status: completed) - Passed library/downstream validation and the live AX/FountainStore drive; prepared the SemVer `0.2.0` release for the downstream pin.
Validation:
- `swift test`
- `swift test --package-path apps/modernization-studio --filter 'ChatRichTextFormatterTests|ReferenceLaneTests|ReferencedKnowledgeStateTests|WikipediaReferenceSourceTests'`
- `swift build --package-path apps/modernization-studio --product ReframeApp`
- Live AX smoke: proposal → authorised lookup → evidence → accepted identity → reference ledger; verify concise card plus accessible retrieval disclosure.