Fountain import (round-trip-safe)

[stultus]

What

Import .fountain files into Scriptty as a Film, into a Series as a new Episode, or open via the standard Open dialog (auto-detected by extension). Round-trip safe — a co-writer can send a .fountain, the Scriptty user edits it, exports back to Fountain, and no data is silently lost.

Why

Fountain is the lingua-franca plaintext format for screenplays. Co-writing across tools (Final Draft, Highland, WriterDuet, Scriptty) usually happens via Fountain hand-offs. Without import, Scriptty is a one-way valve — writers can leave Fountain but never come back.

Hrishi co-writes with two others, splitting scenes across files. A round-trip-safe Fountain pipeline is the unblock for that workflow.

Scope decisions (locked)

Fountain feature	Scriptty mapping
Scene Heading, Action, Character, Parenthetical, Dialogue, Transition	Native ProseMirror nodes
Title page — standard keys (Title, Credit, Author/s, Draft date, Contact)	meta.title, meta.author, meta.draft_date, meta.contact
Title page — non-standard keys (Source, Notes, Copyright, custom)	meta.extra map (new schema field)
Synopses (= ...)	scene_cards[].description of the matching scene
Sections (# ...)	scene_cards[].notes of the next scene, prefixed with depth marker for round-trip
Inline notes ([[ ... ]])	scene_cards[].notes of the containing scene (positional fidelity sacrificed)
Boneyard (/* ... */)	Dropped. Documented in import summary toast.
Dual dialogue (^)	Collapsed to sequential Character/Dialogue pairs
Centered text (> ... <)	Action paragraph

No new ProseMirror node types, no editor schema bump. Only meta.extra is added to the .screenplay JSON.

Entry points

• File → Import Fountain... (always creates a new Film, untitled)
• File → Import Fountain as Episode... (only enabled when a Series is open; appends a new episode)
• Open dialog accepts .fountain alongside .screenplay — auto-imports as a Film
• Per-episode Fountain export for Series projects (writes 01-pilot.fountain, 02-the-return.fountain, ...)

Sub-issues

• Schema: meta.extra for non-standard Fountain title-page keys #185 — Schema: meta.extra map
• Fountain parser (Rust): .fountain → ProseMirror JSON + meta + scene_cards #186 — Fountain parser (Rust)
• Fountain import: frontend wiring (menu, Open dialog, Import as Episode, per-episode export) #187 — Frontend wiring (menu, Open dialog, Import as Episode, per-episode export)
• Fountain export: round-trip synopses, sections, inline notes, meta.extra #188 — Fountain export round-trip (synopses, sections, notes, meta.extra)

Suggested merge order: #185 → #186 → #187 → #188. The export round-trip lands last so it can be exercised against real imported data.

Out of scope (this feature)

• FDX import (separate format, separate parser)
• Editor visualization for Fountain notes / boneyard
• Promoting outline (sections) to a real document-level structure with hierarchy

Notes

CLAUDE.md previously listed Fountain import in the deferred section — this issue un-defers it. Remove from deferred list as part of #186.

[stultus]

Spec research findings (locks parser/export design)

Done a thorough pass on the canonical spec (https://fountain.io/syntax/), the Objective-C reference implementation (nyousefi/Fountain), and wildwinter/screenplay-tools. Key items that change or tighten the plan:

1. Malayalam character cues are a hard correctness issue

Fountain's character auto-detection requires the line to be all uppercase Latin. Malayalam has no concept of case. The spec calls this out — the @ forced-character prefix exists explicitly "to account for names that are in other languages that cannot be capitalized."

Implication for round-trip: every Malayalam (or lowercase / mixed-script) character cue must be exported with @ prefixed, otherwise the next reader sees it as Action. This is not optional. (#188 must enforce this.)

Implication for import: without @, a Malayalam character cue followed by what looks like dialogue is unrecoverable — it'll parse as Action. The @ prefix is the only trustworthy signal. (#186 must trust @-prefixed Malayalam as a character regardless of caps; documented limitation otherwise.)

2. Boneyard is global, not line-local

/* ... */ is the only Fountain syntax allowed to cross double-line-breaks (spec is explicit). The parser must strip boneyards as a global pre-pass before any line-by-line tokenization. We're dropping boneyard content per #184 scope, but the pre-pass is still required to avoid corrupting the rest of the file.

3. All-caps action lines need ! on export

Any action paragraph that's all uppercase (e.g. BANG!, THE WIND HOWLS.) — if followed by a non-empty next line, will be misread as a character cue on re-import. Same hazard for action ending in TO: (misread as transition).

Rule for #188 export: if a stored Action node would auto-detect as anything other than Action when re-emitted, prefix !. Same idea for forced scene headings (.), forced transitions (>), and forced characters (@).

4. Title-page key list updated

Standard keys (case-insensitive in every major impl): Title, Credit, Author, Authors, Source, Notes, Draft date, Date, Contact, Copyright. Authors and Date are aliases for Author and Draft date. Multi-line values continue on indented lines (3+ spaces or tab).

meta.extra (#185) holds anything not mapped to a first-class field, preserved verbatim with original key casing for round-trip.

5. Element precedence (locks parser order — #186)

From the reference implementation's FastFountainParser:

1. Boneyard global pre-pass (/* ... */)
2. Note extraction ([[ ... ]]) — also can cross lines
3. Title page (top of file only, until first blank+non-key line)
4. Forced prefixes: . ! @ > ~ = #
5. Page break (=== or more)
6. Centered (> text <)
7. Scene heading auto-detect (INT/EXT/EST/I/E prefix + blanks around)
8. Transition auto-detect (caps + ends in TO:, plus FADE IN:)
9. Character auto-detect (caps + alpha + non-empty next line + blank prev)
10. Parenthetical (context: prev was Character/Dialogue)
11. Dialogue (context: prev was Character/Parenthetical)
12. Action (fallback)

6. Two-space trailing whitespace is load-bearing

Inside dialogue blocks and notes, a "blank-looking" line with two trailing spaces keeps the element alive across what would otherwise be a paragraph break. Stripping trailing whitespace blindly = silent data corruption. The parser must distinguish "fully blank" from "two-space blank".

7. Sections override scene headings

# INT. HOUSE - DAY is a Section (depth 1) with title "INT. HOUSE - DAY", not a scene heading. Forced prefix wins. Important when sections are interleaved with scenes in pre-writing.

8. Emphasis (*/**/***/_) — confirmed scoped out of v1

Reference implementations leave the markers in the parser output for the renderer to interpret. v1 will strip the markers and keep the text content (with backslash-escape unescaping). This is documented data loss; can be promoted later by mapping to ProseMirror bold/italic/underline marks since Scriptty already has FormatBubble.

9. Scene numbers (#1A#)

Fountain allows custom scene numbers appended to scene headings. Scriptty auto-numbers via scene_number_start, so we drop custom scene numbers on import. Round-trip will lose them — documented in the import summary toast.

10. FADE IN: is divergent across implementations

Reference impl treats as Transition; Fountain.js treats as Action. We follow the reference impl: FADE IN: as a top-of-file transition.

---

Updating #186 (parser) and #188 (export) with these specifics next.

[stultus]

All four sub-issues landed:

• Schema: meta.extra for non-standard Fountain title-page keys #185 schema (c28e8e2)
• Fountain parser (Rust): .fountain → ProseMirror JSON + meta + scene_cards #186 parser (dc754c5)
• Fountain import: frontend wiring (menu, Open dialog, Import as Episode, per-episode export) #187 wiring (07dd628)
• Fountain export: round-trip synopses, sections, inline notes, meta.extra #188 round-trip (afb03d8)

End-to-end testing requires the Tauri dev build (native menu + dialogs are not reachable from the browser dev server).