Trama ✍️

A file-first desktop application for writers and worldbuilders, built with Electron, Preact, and Tailwind CSS.

Trama opens a folder on your machine and works directly with standard Markdown files and YAML frontmatter. Your manuscript, outline, and lore stay on disk in formats you can edit anywhere.

🚀 Features

✅ Currently Implemented

Project & files

File-first workflow — Data lives in your folders; Trama reads and writes real .md files and keeps .trama.index.json in sync.
Section sidebar — Trees scoped to book/, outline/, and lore/ with filter, create/rename/delete, and drag-and-drop reorder.
Smart conflict handling — Detects external file changes and helps you resolve edits safely.
Git version history — Save snapshots, browse revisions per document, preview past versions in the editor, and restore when you need to roll back. Local Git on your machine; no remote or account required.

Editing

Rich Markdown editor — Quill-based visual editing with Markdown persistence and YAML frontmatter.
Split workspace — Two panes side by side, draggable divider, per-pane back/forward history, and shared zoom.
Focus mode & fullscreen — Distraction-free writing with line, sentence, or paragraph emphasis around the caret.
Paste from Markdown — Clipboard Markdown becomes rich editor content.
Smart typography — Common shortcuts (e.g. -- → em dash) with undo support.
Wiki tag links — Tag index stays fresh after saves; Ctrl/Cmd+click jumps to linked documents.
Images — Embedded images are stored under project-local res/ when you save.

Special document types

Map documents — Image-based maps with pan/zoom and interactive markers tied to your lore.

Themes & chrome

Appearance — Light, dark, and system themes.
Context menu — Workspace actions (split, focus, export, and more) from the native right-click menu.

Import, export & integrations

AI import / export — Structured clipboard import (=== FILE: … ===) with preview and replace/append modes; export selected project files for LLM workflows, with optional frontmatter stripping.
Book export — Multi-format export (Markdown, HTML, DOCX, EPUB, PDF) with layout directives and images.
ZuluPad import — Bring .zulu notes into your project structure.

⏳ Planned

Project templates — Pre-defined schemas for characters, locations, and world-building notes.

🛠️ Tech Stack

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

📦 Getting Started

Prerequisites

Node.js (Project uses package.json with ESM)
npm

Installation

Clone the repository:

git clone https://github.com/luisoncpp/trama.git
cd trama

Install dependencies:
```
npm install
```

Development

Run the development server (starts both Vite and Electron):

npm run dev

Testing

Run the test suite (Vitest):

npm run test

In agent or sandboxed environments, prefer the PowerShell runner:

powershell -ExecutionPolicy Bypass -File scripts/run-tests.ps1

For smoke tests (requires build):

npm run test:smoke

Building

To create a production-ready Windows installer:

npm run dist:win

To build without packaging:

npm run pack:win

📂 Project Structure

electron/: Main process, IPC handlers, and services (TypeScript).
- ipc/handlers/: Typed IPC handler modules (project, AI, book export, Zulu, Git history).
- services/: Document repository, index service, watcher, export pipelines.
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.
mds/: Design specifications, architecture docs, implementation plans, and lessons learned.
tests/: Comprehensive test suite (unit, integration, and smoke tests).

🧭 Developer Documentation Entry

If you are starting a new implementation conversation, begin with:

mds/START-HERE.md

This entrypoint routes to the mandatory docs that are often missed:

🤝 Contributing

Contributions are welcome. Please read mds/dev-workflow.md for the development workflow, testing requirements, and documentation update protocol.

📄 License

GPL-3.0-or-later - see the LICENSE file for details.

Trama ✍️

A file-first desktop application for writers and worldbuilders, built with Electron, Preact, and Tailwind CSS.

Trama opens a folder on your machine and works directly with standard Markdown files and YAML frontmatter. Your manuscript, outline, and lore stay on disk in formats you can edit anywhere.

🚀 Features

✅ Currently Implemented

Project & files

File-first workflow — Data lives in your folders; Trama reads and writes real .md files and keeps .trama.index.json in sync.
Section sidebar — Trees scoped to book/, outline/, and lore/ with filter, create/rename/delete, and drag-and-drop reorder.
Smart conflict handling — Detects external file changes and helps you resolve edits safely.
Git version history — Save snapshots, browse revisions per document, preview past versions in the editor, and restore when you need to roll back. Local Git on your machine; no remote or account required.

Editing

Rich Markdown editor — Quill-based visual editing with Markdown persistence and YAML frontmatter.
Split workspace — Two panes side by side, draggable divider, per-pane back/forward history, and shared zoom.
Focus mode & fullscreen — Distraction-free writing with line, sentence, or paragraph emphasis around the caret.
Paste from Markdown — Clipboard Markdown becomes rich editor content.
Smart typography — Common shortcuts (e.g. -- → em dash) with undo support.
Wiki tag links — Tag index stays fresh after saves; Ctrl/Cmd+click jumps to linked documents.
Images — Embedded images are stored under project-local res/ when you save.

Special document types

Map documents — Image-based maps with pan/zoom and interactive markers tied to your lore.

Themes & chrome

Appearance — Light, dark, and system themes.
Context menu — Workspace actions (split, focus, export, and more) from the native right-click menu.

Import, export & integrations

AI import / export — Structured clipboard import (=== FILE: … ===) with preview and replace/append modes; export selected project files for LLM workflows, with optional frontmatter stripping.
Book export — Multi-format export (Markdown, HTML, DOCX, EPUB, PDF) with layout directives and images.
ZuluPad import — Bring .zulu notes into your project structure.

⏳ Planned

Project templates — Pre-defined schemas for characters, locations, and world-building notes.

🛠️ Tech Stack

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

📦 Getting Started

Prerequisites

Node.js (Project uses package.json with ESM)
npm

Installation

Clone the repository:

git clone https://github.com/luisoncpp/trama.git
cd trama

Install dependencies:
```
npm install
```

Development

Run the development server (starts both Vite and Electron):

npm run dev

Testing

Run the test suite (Vitest):

npm run test

In agent or sandboxed environments, prefer the PowerShell runner:

powershell -ExecutionPolicy Bypass -File scripts/run-tests.ps1

For smoke tests (requires build):

npm run test:smoke

Building

To create a production-ready Windows installer:

npm run dist:win

To build without packaging:

npm run pack:win

📂 Project Structure

electron/: Main process, IPC handlers, and services (TypeScript).
- ipc/handlers/: Typed IPC handler modules (project, AI, book export, Zulu, Git history).
- services/: Document repository, index service, watcher, export pipelines.
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.
mds/: Design specifications, architecture docs, implementation plans, and lessons learned.
tests/: Comprehensive test suite (unit, integration, and smoke tests).

🧭 Developer Documentation Entry

If you are starting a new implementation conversation, begin with:

mds/START-HERE.md

This entrypoint routes to the mandatory docs that are often missed:

🤝 Contributing

Contributions are welcome. Please read mds/dev-workflow.md for the development workflow, testing requirements, and documentation update protocol.

📄 License

GPL-3.0-or-later - see the LICENSE file for details.

Trama ✍️

A file-first desktop application for writers and worldbuilders, built with Electron, Preact, and Tailwind CSS.

Trama opens a folder on your machine and works directly with standard Markdown files and YAML frontmatter. Your manuscript, outline, and lore stay on disk in formats you can edit anywhere.

🚀 Features

✅ Currently Implemented

Project & files

File-first workflow — Data lives in your folders; Trama reads and writes real .md files and keeps .trama.index.json in sync.
Section sidebar — Trees scoped to book/, outline/, and lore/ with filter, create/rename/delete, and drag-and-drop reorder.
Smart conflict handling — Detects external file changes and helps you resolve edits safely.
Git version history — Save snapshots, browse revisions per document, preview past versions in the editor, and restore when you need to roll back. Local Git on your machine; no remote or account required.

Editing

Rich Markdown editor — Quill-based visual editing with Markdown persistence and YAML frontmatter.
Split workspace — Two panes side by side, draggable divider, per-pane back/forward history, and shared zoom.
Focus mode & fullscreen — Distraction-free writing with line, sentence, or paragraph emphasis around the caret.
Paste from Markdown — Clipboard Markdown becomes rich editor content.
Smart typography — Common shortcuts (e.g. -- → em dash) with undo support.
Wiki tag links — Tag index stays fresh after saves; Ctrl/Cmd+click jumps to linked documents.
Images — Embedded images are stored under project-local res/ when you save.

Special document types

Map documents — Image-based maps with pan/zoom and interactive markers tied to your lore.

Themes & chrome

Appearance — Light, dark, and system themes.
Context menu — Workspace actions (split, focus, export, and more) from the native right-click menu.

Import, export & integrations

AI import / export — Structured clipboard import (=== FILE: … ===) with preview and replace/append modes; export selected project files for LLM workflows, with optional frontmatter stripping.
Book export — Multi-format export (Markdown, HTML, DOCX, EPUB, PDF) with layout directives and images.
ZuluPad import — Bring .zulu notes into your project structure.

⏳ Planned

Project templates — Pre-defined schemas for characters, locations, and world-building notes.

🛠️ Tech Stack

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

📦 Getting Started

Prerequisites

Node.js (Project uses package.json with ESM)
npm

Installation

Clone the repository:

git clone https://github.com/luisoncpp/trama.git
cd trama

Install dependencies:
```
npm install
```

Development

Run the development server (starts both Vite and Electron):

npm run dev

Testing

Run the test suite (Vitest):

npm run test

In agent or sandboxed environments, prefer the PowerShell runner:

powershell -ExecutionPolicy Bypass -File scripts/run-tests.ps1

For smoke tests (requires build):

npm run test:smoke

Building

To create a production-ready Windows installer:

npm run dist:win

To build without packaging:

npm run pack:win

📂 Project Structure

electron/: Main process, IPC handlers, and services (TypeScript).
- ipc/handlers/: Typed IPC handler modules (project, AI, book export, Zulu, Git history).
- services/: Document repository, index service, watcher, export pipelines.
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.
mds/: Design specifications, architecture docs, implementation plans, and lessons learned.
tests/: Comprehensive test suite (unit, integration, and smoke tests).

🧭 Developer Documentation Entry

If you are starting a new implementation conversation, begin with:

mds/START-HERE.md

This entrypoint routes to the mandatory docs that are often missed:

🤝 Contributing

Contributions are welcome. Please read mds/dev-workflow.md for the development workflow, testing requirements, and documentation update protocol.

📄 License

GPL-3.0-or-later - see the LICENSE file for details.

Trama ✍️

A file-first desktop application for writers and worldbuilders, built with Electron, Preact, and Tailwind CSS.

Trama opens a folder on your machine and works directly with standard Markdown files and YAML frontmatter. Your manuscript, outline, and lore stay on disk in formats you can edit anywhere.

🚀 Features

✅ Currently Implemented

Project & files

File-first workflow — Data lives in your folders; Trama reads and writes real .md files and keeps .trama.index.json in sync.
Section sidebar — Trees scoped to book/, outline/, and lore/ with filter, create/rename/delete, and drag-and-drop reorder.
Smart conflict handling — Detects external file changes and helps you resolve edits safely.
Git version history — Save snapshots, browse revisions per document, preview past versions in the editor, and restore when you need to roll back. Local Git on your machine; no remote or account required.

Editing

Rich Markdown editor — Quill-based visual editing with Markdown persistence and YAML frontmatter.
Split workspace — Two panes side by side, draggable divider, per-pane back/forward history, and shared zoom.
Focus mode & fullscreen — Distraction-free writing with line, sentence, or paragraph emphasis around the caret.
Paste from Markdown — Clipboard Markdown becomes rich editor content.
Smart typography — Common shortcuts (e.g. -- → em dash) with undo support.
Wiki tag links — Tag index stays fresh after saves; Ctrl/Cmd+click jumps to linked documents.
Images — Embedded images are stored under project-local res/ when you save.

Special document types

Map documents — Image-based maps with pan/zoom and interactive markers tied to your lore.

Themes & chrome

Appearance — Light, dark, and system themes.
Context menu — Workspace actions (split, focus, export, and more) from the native right-click menu.

Import, export & integrations

AI import / export — Structured clipboard import (=== FILE: … ===) with preview and replace/append modes; export selected project files for LLM workflows, with optional frontmatter stripping.
Book export — Multi-format export (Markdown, HTML, DOCX, EPUB, PDF) with layout directives and images.
ZuluPad import — Bring .zulu notes into your project structure.

⏳ Planned

Project templates — Pre-defined schemas for characters, locations, and world-building notes.

🛠️ Tech Stack

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

📦 Getting Started

Prerequisites

Node.js (Project uses package.json with ESM)
npm

Installation

Clone the repository:

git clone https://github.com/luisoncpp/trama.git
cd trama

Install dependencies:
```
npm install
```

Development

Run the development server (starts both Vite and Electron):

npm run dev

Testing

Run the test suite (Vitest):

npm run test

In agent or sandboxed environments, prefer the PowerShell runner:

powershell -ExecutionPolicy Bypass -File scripts/run-tests.ps1

For smoke tests (requires build):

npm run test:smoke

Building

To create a production-ready Windows installer:

npm run dist:win

To build without packaging:

npm run pack:win

📂 Project Structure

electron/: Main process, IPC handlers, and services (TypeScript).
- ipc/handlers/: Typed IPC handler modules (project, AI, book export, Zulu, Git history).
- services/: Document repository, index service, watcher, export pipelines.
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.
mds/: Design specifications, architecture docs, implementation plans, and lessons learned.
tests/: Comprehensive test suite (unit, integration, and smoke tests).

🧭 Developer Documentation Entry

If you are starting a new implementation conversation, begin with:

mds/START-HERE.md

This entrypoint routes to the mandatory docs that are often missed:

🤝 Contributing

Contributions are welcome. Please read mds/dev-workflow.md for the development workflow, testing requirements, and documentation update protocol.

📄 License

GPL-3.0-or-later - see the LICENSE file for details.

Trama ✍️

A file-first desktop application for writers and worldbuilders, built with Electron, Preact, and Tailwind CSS.

Trama opens a folder on your machine and works directly with standard Markdown files and YAML frontmatter. Your manuscript, outline, and lore stay on disk in formats you can edit anywhere.

🚀 Features

✅ Currently Implemented

Project & files

File-first workflow — Data lives in your folders; Trama reads and writes real .md files and keeps .trama.index.json in sync.
Section sidebar — Trees scoped to book/, outline/, and lore/ with filter, create/rename/delete, and drag-and-drop reorder.
Smart conflict handling — Detects external file changes and helps you resolve edits safely.
Git version history — Save snapshots, browse revisions per document, preview past versions in the editor, and restore when you need to roll back. Local Git on your machine; no remote or account required.

Editing

Rich Markdown editor — Quill-based visual editing with Markdown persistence and YAML frontmatter.
Split workspace — Two panes side by side, draggable divider, per-pane back/forward history, and shared zoom.
Focus mode & fullscreen — Distraction-free writing with line, sentence, or paragraph emphasis around the caret.
Paste from Markdown — Clipboard Markdown becomes rich editor content.
Smart typography — Common shortcuts (e.g. -- → em dash) with undo support.
Wiki tag links — Tag index stays fresh after saves; Ctrl/Cmd+click jumps to linked documents.
Images — Embedded images are stored under project-local res/ when you save.

Special document types

Map documents — Image-based maps with pan/zoom and interactive markers tied to your lore.

Themes & chrome

Appearance — Light, dark, and system themes.
Context menu — Workspace actions (split, focus, export, and more) from the native right-click menu.

Import, export & integrations

AI import / export — Structured clipboard import (=== FILE: … ===) with preview and replace/append modes; export selected project files for LLM workflows, with optional frontmatter stripping.
Book export — Multi-format export (Markdown, HTML, DOCX, EPUB, PDF) with layout directives and images.
ZuluPad import — Bring .zulu notes into your project structure.

⏳ Planned

Project templates — Pre-defined schemas for characters, locations, and world-building notes.

🛠️ Tech Stack

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

📦 Getting Started

Prerequisites

Node.js (Project uses package.json with ESM)
npm

Installation

Clone the repository:

git clone https://github.com/luisoncpp/trama.git
cd trama

Install dependencies:
```
npm install
```

Development

Run the development server (starts both Vite and Electron):

npm run dev

Testing

Run the test suite (Vitest):

npm run test

In agent or sandboxed environments, prefer the PowerShell runner:

powershell -ExecutionPolicy Bypass -File scripts/run-tests.ps1

For smoke tests (requires build):

npm run test:smoke

Building

To create a production-ready Windows installer:

npm run dist:win

To build without packaging:

npm run pack:win

📂 Project Structure

electron/: Main process, IPC handlers, and services (TypeScript).
- ipc/handlers/: Typed IPC handler modules (project, AI, book export, Zulu, Git history).
- services/: Document repository, index service, watcher, export pipelines.
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.
mds/: Design specifications, architecture docs, implementation plans, and lessons learned.
tests/: Comprehensive test suite (unit, integration, and smoke tests).

🧭 Developer Documentation Entry

If you are starting a new implementation conversation, begin with:

mds/START-HERE.md

This entrypoint routes to the mandatory docs that are often missed:

🤝 Contributing

Contributions are welcome. Please read mds/dev-workflow.md for the development workflow, testing requirements, and documentation update protocol.

📄 License

GPL-3.0-or-later - see the LICENSE file for details.

Trama ✍️

A file-first desktop application for writers and worldbuilders, built with Electron, Preact, and Tailwind CSS.

Trama opens a folder on your machine and works directly with standard Markdown files and YAML frontmatter. Your manuscript, outline, and lore stay on disk in formats you can edit anywhere.

🚀 Features

✅ Currently Implemented

Project & files

File-first workflow — Data lives in your folders; Trama reads and writes real .md files and keeps .trama.index.json in sync.
Section sidebar — Trees scoped to book/, outline/, and lore/ with filter, create/rename/delete, and drag-and-drop reorder.
Smart conflict handling — Detects external file changes and helps you resolve edits safely.
Git version history — Save snapshots, browse revisions per document, preview past versions in the editor, and restore when you need to roll back. Local Git on your machine; no remote or account required.

Editing

Rich Markdown editor — Quill-based visual editing with Markdown persistence and YAML frontmatter.
Split workspace — Two panes side by side, draggable divider, per-pane back/forward history, and shared zoom.
Focus mode & fullscreen — Distraction-free writing with line, sentence, or paragraph emphasis around the caret.
Paste from Markdown — Clipboard Markdown becomes rich editor content.
Smart typography — Common shortcuts (e.g. -- → em dash) with undo support.
Wiki tag links — Tag index stays fresh after saves; Ctrl/Cmd+click jumps to linked documents.
Images — Embedded images are stored under project-local res/ when you save.

Special document types

Map documents — Image-based maps with pan/zoom and interactive markers tied to your lore.

Themes & chrome

Appearance — Light, dark, and system themes.
Context menu — Workspace actions (split, focus, export, and more) from the native right-click menu.

Import, export & integrations

AI import / export — Structured clipboard import (=== FILE: … ===) with preview and replace/append modes; export selected project files for LLM workflows, with optional frontmatter stripping.
Book export — Multi-format export (Markdown, HTML, DOCX, EPUB, PDF) with layout directives and images.
ZuluPad import — Bring .zulu notes into your project structure.

⏳ Planned

Project templates — Pre-defined schemas for characters, locations, and world-building notes.

🛠️ Tech Stack

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

📦 Getting Started

Prerequisites

Node.js (Project uses package.json with ESM)
npm

Installation

Clone the repository:

git clone https://github.com/luisoncpp/trama.git
cd trama

Install dependencies:
```
npm install
```

Development

Run the development server (starts both Vite and Electron):

npm run dev

Testing

Run the test suite (Vitest):

npm run test

In agent or sandboxed environments, prefer the PowerShell runner:

powershell -ExecutionPolicy Bypass -File scripts/run-tests.ps1

For smoke tests (requires build):

npm run test:smoke

Building

To create a production-ready Windows installer:

npm run dist:win

To build without packaging:

npm run pack:win

📂 Project Structure

electron/: Main process, IPC handlers, and services (TypeScript).
- ipc/handlers/: Typed IPC handler modules (project, AI, book export, Zulu, Git history).
- services/: Document repository, index service, watcher, export pipelines.
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.
mds/: Design specifications, architecture docs, implementation plans, and lessons learned.
tests/: Comprehensive test suite (unit, integration, and smoke tests).

🧭 Developer Documentation Entry

If you are starting a new implementation conversation, begin with:

mds/START-HERE.md

This entrypoint routes to the mandatory docs that are often missed:

🤝 Contributing

Contributions are welcome. Please read mds/dev-workflow.md for the development workflow, testing requirements, and documentation update protocol.

📄 License

GPL-3.0-or-later - see the LICENSE file for details.

Trama ✍️

A file-first desktop application for writers and worldbuilders, built with Electron, Preact, and Tailwind CSS.

Trama opens a folder on your machine and works directly with standard Markdown files and YAML frontmatter. Your manuscript, outline, and lore stay on disk in formats you can edit anywhere.

🚀 Features

✅ Currently Implemented

Project & files

File-first workflow — Data lives in your folders; Trama reads and writes real .md files and keeps .trama.index.json in sync.
Section sidebar — Trees scoped to book/, outline/, and lore/ with filter, create/rename/delete, and drag-and-drop reorder.
Smart conflict handling — Detects external file changes and helps you resolve edits safely.
Git version history — Save snapshots, browse revisions per document, preview past versions in the editor, and restore when you need to roll back. Local Git on your machine; no remote or account required.

Editing

Rich Markdown editor — Quill-based visual editing with Markdown persistence and YAML frontmatter.
Split workspace — Two panes side by side, draggable divider, per-pane back/forward history, and shared zoom.
Focus mode & fullscreen — Distraction-free writing with line, sentence, or paragraph emphasis around the caret.
Paste from Markdown — Clipboard Markdown becomes rich editor content.
Smart typography — Common shortcuts (e.g. -- → em dash) with undo support.
Wiki tag links — Tag index stays fresh after saves; Ctrl/Cmd+click jumps to linked documents.
Images — Embedded images are stored under project-local res/ when you save.

Special document types

Map documents — Image-based maps with pan/zoom and interactive markers tied to your lore.

Themes & chrome

Appearance — Light, dark, and system themes.
Context menu — Workspace actions (split, focus, export, and more) from the native right-click menu.

Import, export & integrations

AI import / export — Structured clipboard import (=== FILE: … ===) with preview and replace/append modes; export selected project files for LLM workflows, with optional frontmatter stripping.
Book export — Multi-format export (Markdown, HTML, DOCX, EPUB, PDF) with layout directives and images.
ZuluPad import — Bring .zulu notes into your project structure.

⏳ Planned

Project templates — Pre-defined schemas for characters, locations, and world-building notes.

🛠️ Tech Stack

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

📦 Getting Started

Prerequisites

Node.js (Project uses package.json with ESM)
npm

Installation

Clone the repository:

git clone https://github.com/luisoncpp/trama.git
cd trama

Install dependencies:
```
npm install
```

Development

Run the development server (starts both Vite and Electron):

npm run dev

Testing

Run the test suite (Vitest):

npm run test

In agent or sandboxed environments, prefer the PowerShell runner:

powershell -ExecutionPolicy Bypass -File scripts/run-tests.ps1

For smoke tests (requires build):

npm run test:smoke

Building

To create a production-ready Windows installer:

npm run dist:win

To build without packaging:

npm run pack:win

📂 Project Structure

electron/: Main process, IPC handlers, and services (TypeScript).
- ipc/handlers/: Typed IPC handler modules (project, AI, book export, Zulu, Git history).
- services/: Document repository, index service, watcher, export pipelines.
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.
mds/: Design specifications, architecture docs, implementation plans, and lessons learned.
tests/: Comprehensive test suite (unit, integration, and smoke tests).

🧭 Developer Documentation Entry

If you are starting a new implementation conversation, begin with:

mds/START-HERE.md

This entrypoint routes to the mandatory docs that are often missed:

🤝 Contributing

Contributions are welcome. Please read mds/dev-workflow.md for the development workflow, testing requirements, and documentation update protocol.

📄 License

GPL-3.0-or-later - see the LICENSE file for details.

Trama ✍️

A file-first desktop application for writers and worldbuilders, built with Electron, Preact, and Tailwind CSS.

Trama opens a folder on your machine and works directly with standard Markdown files and YAML frontmatter. Your manuscript, outline, and lore stay on disk in formats you can edit anywhere.

🚀 Features

✅ Currently Implemented

Project & files

File-first workflow — Data lives in your folders; Trama reads and writes real .md files and keeps .trama.index.json in sync.
Section sidebar — Trees scoped to book/, outline/, and lore/ with filter, create/rename/delete, and drag-and-drop reorder.
Smart conflict handling — Detects external file changes and helps you resolve edits safely.
Git version history — Save snapshots, browse revisions per document, preview past versions in the editor, and restore when you need to roll back. Local Git on your machine; no remote or account required.

Editing

Rich Markdown editor — Quill-based visual editing with Markdown persistence and YAML frontmatter.
Split workspace — Two panes side by side, draggable divider, per-pane back/forward history, and shared zoom.
Focus mode & fullscreen — Distraction-free writing with line, sentence, or paragraph emphasis around the caret.
Paste from Markdown — Clipboard Markdown becomes rich editor content.
Smart typography — Common shortcuts (e.g. -- → em dash) with undo support.
Wiki tag links — Tag index stays fresh after saves; Ctrl/Cmd+click jumps to linked documents.
Images — Embedded images are stored under project-local res/ when you save.

Special document types

Map documents — Image-based maps with pan/zoom and interactive markers tied to your lore.

Themes & chrome

Appearance — Light, dark, and system themes.
Context menu — Workspace actions (split, focus, export, and more) from the native right-click menu.

Import, export & integrations

AI import / export — Structured clipboard import (=== FILE: … ===) with preview and replace/append modes; export selected project files for LLM workflows, with optional frontmatter stripping.
Book export — Multi-format export (Markdown, HTML, DOCX, EPUB, PDF) with layout directives and images.
ZuluPad import — Bring .zulu notes into your project structure.

⏳ Planned

Project templates — Pre-defined schemas for characters, locations, and world-building notes.

🛠️ Tech Stack

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

📦 Getting Started

Prerequisites

Node.js (Project uses package.json with ESM)
npm

Installation

Clone the repository:

git clone https://github.com/luisoncpp/trama.git
cd trama

Install dependencies:
```
npm install
```

Development

Run the development server (starts both Vite and Electron):

npm run dev

Testing

Run the test suite (Vitest):

npm run test

In agent or sandboxed environments, prefer the PowerShell runner:

powershell -ExecutionPolicy Bypass -File scripts/run-tests.ps1

For smoke tests (requires build):

npm run test:smoke

Building

To create a production-ready Windows installer:

npm run dist:win

To build without packaging:

npm run pack:win

📂 Project Structure

electron/: Main process, IPC handlers, and services (TypeScript).
- ipc/handlers/: Typed IPC handler modules (project, AI, book export, Zulu, Git history).
- services/: Document repository, index service, watcher, export pipelines.
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.
mds/: Design specifications, architecture docs, implementation plans, and lessons learned.
tests/: Comprehensive test suite (unit, integration, and smoke tests).

🧭 Developer Documentation Entry

If you are starting a new implementation conversation, begin with:

mds/START-HERE.md

This entrypoint routes to the mandatory docs that are often missed:

🤝 Contributing

Contributions are welcome. Please read mds/dev-workflow.md for the development workflow, testing requirements, and documentation update protocol.

📄 License

GPL-3.0-or-later - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
build		build
docs		docs
electron		electron
example-fantasy		example-fantasy
help		help
mds		mds
public		public
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTEXT.md		CONTEXT.md
DESIGN_SPEC.md		DESIGN_SPEC.md
LICENSE		LICENSE
README.md		README.md
REQUIREMENTS.md		REQUIREMENTS.md
eslint.config.js		eslint.config.js
icon.png		icon.png
index.html		index.html
markdownsForTask.md		markdownsForTask.md
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
test-render.html		test-render.html
trama.group.md		trama.group.md
tsconfig.app.json		tsconfig.app.json
tsconfig.electron.json		tsconfig.electron.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.tests.json		tsconfig.tests.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vite.config.ts		vite.config.ts

Name		Name	Last commit message	Last commit date
build		build
docs		docs
electron		electron
example-fantasy		example-fantasy
help		help
mds		mds
public		public
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTEXT.md		CONTEXT.md
DESIGN_SPEC.md		DESIGN_SPEC.md
LICENSE		LICENSE
README.md		README.md
REQUIREMENTS.md		REQUIREMENTS.md
eslint.config.js		eslint.config.js
icon.png		icon.png
index.html		index.html
markdownsForTask.md		markdownsForTask.md
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
test-render.html		test-render.html
trama.group.md		trama.group.md
tsconfig.app.json		tsconfig.app.json
tsconfig.electron.json		tsconfig.electron.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.tests.json		tsconfig.tests.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vite.config.ts		vite.config.ts

Name		Name	Last commit message	Last commit date
build		build
docs		docs
electron		electron
example-fantasy		example-fantasy
help		help
mds		mds
public		public
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTEXT.md		CONTEXT.md
DESIGN_SPEC.md		DESIGN_SPEC.md
LICENSE		LICENSE
README.md		README.md
REQUIREMENTS.md		REQUIREMENTS.md
eslint.config.js		eslint.config.js
icon.png		icon.png
index.html		index.html
markdownsForTask.md		markdownsForTask.md
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
test-render.html		test-render.html
trama.group.md		trama.group.md
tsconfig.app.json		tsconfig.app.json
tsconfig.electron.json		tsconfig.electron.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.tests.json		tsconfig.tests.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vite.config.ts		vite.config.ts

Name		Name	Last commit message	Last commit date
build		build
docs		docs
electron		electron
example-fantasy		example-fantasy
help		help
mds		mds
public		public
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTEXT.md		CONTEXT.md
DESIGN_SPEC.md		DESIGN_SPEC.md
LICENSE		LICENSE
README.md		README.md
REQUIREMENTS.md		REQUIREMENTS.md
eslint.config.js		eslint.config.js
icon.png		icon.png
index.html		index.html
markdownsForTask.md		markdownsForTask.md
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
test-render.html		test-render.html
trama.group.md		trama.group.md
tsconfig.app.json		tsconfig.app.json
tsconfig.electron.json		tsconfig.electron.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.tests.json		tsconfig.tests.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vite.config.ts		vite.config.ts

Name		Name	Last commit message	Last commit date
build		build
docs		docs
electron		electron
example-fantasy		example-fantasy
help		help
mds		mds
public		public
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTEXT.md		CONTEXT.md
DESIGN_SPEC.md		DESIGN_SPEC.md
LICENSE		LICENSE
README.md		README.md
REQUIREMENTS.md		REQUIREMENTS.md
eslint.config.js		eslint.config.js
icon.png		icon.png
index.html		index.html
markdownsForTask.md		markdownsForTask.md
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
test-render.html		test-render.html
trama.group.md		trama.group.md
tsconfig.app.json		tsconfig.app.json
tsconfig.electron.json		tsconfig.electron.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.tests.json		tsconfig.tests.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation

Trama ✍️

🚀 Features

✅ Currently Implemented

⏳ Planned

🛠️ Tech Stack

📦 Getting Started

Prerequisites

Installation

Development

Testing

Building

📂 Project Structure

🧭 Developer Documentation Entry

🤝 Contributing

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Trama ✍️

🚀 Features

✅ Currently Implemented

⏳ Planned

🛠️ Tech Stack

📦 Getting Started

Prerequisites

Installation

Development

Testing

Building

📂 Project Structure

🧭 Developer Documentation Entry

🤝 Contributing

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Trama ✍️

🚀 Features

✅ Currently Implemented

⏳ Planned

🛠️ Tech Stack

📦 Getting Started

Prerequisites

Installation

Development

Testing

Building

📂 Project Structure

🧭 Developer Documentation Entry

🤝 Contributing

📄 License

About

Topics

Resources