The Five Actors

Think of FINAL|FINAL like a theater production. Each component has a single, well-defined role. When something breaks, knowing who's responsible tells you where to look.

How They're Arranged

Click any component to see what it does:

A Conversation Between Components

Here's what happens when you type a new heading. Watch the components talk to each other:

Two Languages, One App

The outer shell (toolbar, sidebar) is written in Swift. The inner editors are written in JavaScript. They run in completely different worlds -- like two diplomats who need a translator.

The bridge is window.FinalFinal -- a shared API that both sides use. Swift calls JavaScript functions to ask questions. JavaScript calls Swift message handlers to send updates back.

The API Menu

Here's what Swift can ask the editors to do:

Push + Poll

Two communication patterns run simultaneously, each optimized for different kinds of data:

Why both? Push gives speed for the content itself. Polling gives efficiency for structural metadata. It's like a newsroom: breaking news goes out immediately (push), but the daily summary is compiled on a schedule (poll).

See It In Action

Click "Next Step" to trace what happens when you type a heading:

The Polling Code

BlockSyncService uses a repeating 2-second timer to check for structural changes. Here's the function that starts this loop -- it creates a timer that calls pollBlockChanges() on every tick:

func startPolling() {
    stopPolling()
    pollTimer = Timer.scheduledTimer(
        withTimeInterval: pollInterval,
        repeats: true
    ) { [weak self] _ in
        Task { @MainActor in
            await self?.pollBlockChanges()
        }
    }
}

A Portable Package

Your entire project is a single macOS package -- a folder that appears as one file in Finder. You can back it up or share it just by copying:

Everything Is a Block

Your document isn't stored as one big blob of text. Instead, imagine a spreadsheet where each row is a structural element -- a paragraph, a heading, a list, a code block. Each row has a unique ID (a permanent fingerprint), a sort order (a decimal number that determines position), a type, and the actual content.

Here's the blueprint for that spreadsheet -- the database table that holds every block:

CREATE TABLE block (
    id         TEXT PRIMARY KEY,
    sortOrder  DOUBLE NOT NULL,
    blockType  TEXT NOT NULL,
    textContent  TEXT NOT NULL,
    markdownFragment TEXT NOT NULL,
    headingLevel INTEGER,
    status     TEXT,
    wordCount  INTEGER DEFAULT 0
);

The Fractional Sort Order Trick

How do you insert a new paragraph between two existing ones without renumbering everything? Use decimal sort orders and pick a number in between:

Same Song, Two Instruments

Milkdown and CodeMirror both display the exact same content from the vault, but in completely different formats. Press Cmd+/ to toggle between them. The database view below is what's actually stored on disk -- both editors are just different lenses on the same data.

## Literature Review

The study of **vibe coding** has shown that non-technical users can build sophisticated software [@smith2024].

Previous research suggests that *understanding architecture* is the key skill.

Tracking Identity Across Editors

Both editors need to know which block is which so changes sync to the right database row. They solve this differently because they have fundamentally different document models:

When you switch editors, the app translates between these systems: extracting node attributes into comment anchors, or vice versa.

The Traffic Controller

Switching editors, zooming into a section, and dragging to reorder all involve replacing the editor's content. If two happen simultaneously, data gets corrupted. The app uses a state machine -- only one transition at a time:

The Supply Chain

The Citation Journey

When you type /cite and select a paper:

Checking Zotero's Availability

Before citations work, the app sends a quick "are you there?" request to Zotero's local server. Here's the code -- it defines a thread-safe checker that connects to Zotero on your own machine and sends a minimal test request:

actor ZoteroChecker {
    private let statusEndpoint =
        "http://127.0.0.1:23119/
         better-bibtex/json-rpc"

    func check() async
        -> ZoteroStatus {
        // Send a minimal request
        // to see if Zotero responds
    }
}

Architecture Decisions

Every choice was a tradeoff. Understanding why things were built this way is what lets you steer AI coding tools confidently:

Debugging Map

When something breaks, here's where to look:

That's the Full Picture

FINAL|FINAL combines a hybrid native/web architecture, database-first storage, block-based content, state machines, and external integrations into a cohesive writing tool.