I/O Adapters

All file I/O operations are abstracted behind a common WritableDirectoryAdapter interface. This allows the application to switch seamlessly between local disk and remote Git providers.

Local FS Adapter

File System Access API

Operates on a FileSystemDirectoryHandle provided by the user. Edits are saved directly to disk. This mode is 100% offline and requires zero network activity.

Remote Git Adapter

GitHub / GitLab REST

Uses OAuth tokens to pull the .quill.md/ directory via the Trees API. Commits are pushed sequentially to an orphan branch.

Orphan Branch Requirement

quill.md explicitly isolates itself from source code by writing only to an orphan branch named quill-md. It does not touch main or master.

IndexedDB Caching

For remote modes, reading hundreds of markdown files via REST on every page load is too slow. The adapter layer wraps remote reads in an IndexedDB caching layer.

Fetches the latest Git SHA for the branch.
Compares it to the cached SHA.
Only downloads files whose SHAs have changed since the last fetch.