A file-first desktop application for writers and worldbuilders, built with Electron, Preact, and Tailwind CSS.
Trama is designed for managing long-form manuscripts and complex lore through a local-first philosophy, using standard Markdown files with YAML frontmatter.
- File-First Architecture: Your data stays in your folders. Trama works directly with the local file system.
- Semantic Project Tree: A specialized sidebar designed for writers with distinct sections for Manuscripts, Lore, Characters, Locations, and more.
- Rich Markdown Editor: A Quill-based editing experience with full Markdown persistence, YAML frontmatter integration, and inline find.
- Split Pane Workspace: Multi-pane support to keep notes, lore, and manuscript side-by-side.
- Focus Mode & Fullscreen: Zero-distraction writing environment with native fullscreen and configurable line, sentence, or paragraph focus scope.
- Document Zoom: Zoom in/out via Ctrl++/Ctrl+- shared across twin panes.
- Appearance: Support for Light, Dark, and System themes.
- AI Import / Export: Structured clipboard import and multi-file export flows for working with LLMs without leaving the file-first model.
- Paste Markdown: Convert Markdown from the clipboard directly into the rich editor.
- Wiki Tag Navigation: Tag index refreshes after saves so Ctrl/Cmd+Click tag navigation remains reliable.
- Smart Conflict Resolution: Built-in watcher detects external changes and helps resolve edit conflicts.
- Folder Operations: Safe rename, delete, and move workflows with subtree tracking and index reconciliation.
- Drag-and-Drop Reorder: Reorder files and move them between folders with visual drop indicators and corkboard order persistence.
- Book Export: Multi-format export (Markdown, HTML, DOCX, EPUB, PDF) with layout directives and image support.
- ZuluPad Import: Import ZuluPad
.zuludocuments into your project structure. - Spellcheck: Configurable spellcheck with language selection and optimistic UI sync.
- Project Templates: Pre-defined schemas for characters, locations, and world-building notes.
- Corkboard View: Drag-and-drop cards for planning and reorganizing scenes or ideas.
- Backend: Electron 41.x (Node.js for native FS access)
- Frontend: Preact 10.x + Vite 8.x
- Styling: Tailwind CSS 4.x
- Editor: Quill 2.x (Custom Markdown integration)
- Validation: Zod 3.x for IPC contracts
- PDF Generation: pdf-lib 1.x
- DOCX Generation: docx 9.x
- EPUB Generation: epub-gen 0.1.x
- YAML Parsing: yaml 2.x
- Node.js (Project uses
package.jsonwith ESM) - npm
- Clone the repository:
git clone https://github.com/luisoncpp/trama.git cd trama - Install dependencies:
npm install
Run the development server (starts both Vite and Electron):
npm run devRun the test suite (Vitest):
npm run testIn agent or sandboxed environments, prefer the PowerShell runner:
powershell -ExecutionPolicy Bypass -File scripts/run-tests.ps1For smoke tests (requires build):
npm run test:smokeTo create a production-ready Windows installer:
npm run dist:winTo build without packaging:
npm run pack:winelectron/: Main process, IPC handlers, and services (TypeScript).ipc/handlers/: Typed IPC handler modules (project, AI, book export, Zulu).services/: Document repository, index service, watcher, book export pipeline.
src/: Preact renderer source code.features/project-editor/: Domain-driven feature modules (Editor, Sidebar, Pane workspace).shared/: Shared IPC types and constants between Main and Renderer.
docs/: Design specifications, architecture docs, implementation plans, and lessons learned.tests/: Comprehensive test suite (unit, integration, and smoke tests).
If you are starting a new implementation conversation, begin with:
This entrypoint routes to the mandatory docs that are often missed:
- docs/live/current-status.md
- docs/live/file-map.md
- docs/lessons-learned/README.md
- docs/dev-workflow.md
Contributions are welcome. Please read docs/dev-workflow.md for the development workflow, testing requirements, and documentation update protocol.
GPL-3.0-or-later - see the LICENSE file for details.