# PubScript

**A self-hostable, multi-user writing studio for novelists — one codebase that runs as a web application and as a native Linux desktop application, with a local-first AI co-writing engine built in.**

---

## Key Features

- **Manuscript Writing Studio**: Rich-text manuscript editor powered by TipTap 3 with an OnlyOffice/Word-inspired formatting ribbon, **34 curated typography options** (serif, display, sans-serif, and monospace), adjustable font sizes, line spacing, column width, first-line paragraph indentation, scene breaks (`* * *`), footnotes, `@` character mentions, line numbers, and a distraction-free **Focus Mode** (`F2`).
- **Autosave & Revision History**: Continuous background autosave with per-chapter revision snapshots (`rev #1`, `rev #2`, …) and one-click revision restore directly from the sidebar or context rail.
- **Offline Spell & Grammar Checking**: Browser-safe Hunspell WebAssembly spellchecker + built-in prose grammar/style checks with inline squiggles and instant replacement popovers.
- **AI Co-Writing Studio**:
  - First-class support for local AI servers (**Ollama**, **llama.cpp**, **LM Studio**, any OpenAI-compatible endpoint) alongside **OpenAI**, **Anthropic**, **Google Gemini**, and **OpenRouter**.
  - Configurable role agents (**Editor**, **Reader**, **Publisher**, **Co-Author**, or custom agents) with per-agent system prompts, temperature, context window (`ctx`), max output tokens, and extended thinking/reasoning controls.
  - **Granular Text-Anchored Inline Suggestions**: Suggestions peg directly to verbatim phrases, clauses, and sentences in your manuscript. Stepping through suggestions highlights the exact span in the editor (`Accept` applies the edit in place and advances to the next suggestion; `Deny` dismisses it; `Copy to Note` moves it to session notes).
  - Resizable AI sidebar (with snap-to-default `370px`), live thinking indicator, and non-intrusive context usage & throughput (`t/s`) telemetry.
- **Story Structure, World-Building & Whiteboard**:
  - **Guided Story Structure Wizard**: Interactive project setup recommending **Save the Cat! (15 Beats)**, **Three-Act Structure**, **Seven-Point Story Structure**, or **Custom / Discovery** templates.
  - **Entities & Lore**: Dedicated views for **People**, **Places & World**, and **Notes** with automatic backlink tracking across chapters.
  - **Plot Beats & Interactive Whiteboard**: Drag-and-drop Act I–III plot beat cards and a ReactFlow canvas for mapping chapters, characters, world items, and custom connection lines.
- **Publishing-Grade Manuscript Export**: Deterministic export to **Markdown (`.md`)**, **HTML (`.html`)**, **EPUB 3 (`.epub`)**, **DOCX (`.docx`)**, **ODT (`.odt`)**, and **Print-Ready PDF (`.pdf`)**.
- **Multi-User Administration**: Built-in Admin console for user creation, role assignment (`Author` / `Admin`), account enable/disable, instance statistics, and filterable audit logs.

---

## Installation

### Option 1: Linux Desktop Application (`.deb` — Ubuntu / Debian / Linux Mint)

Download `pubscript_0.1.0_amd64.deb` from the [GitHub Releases](https://github.com/Schwitzz/PubScript/releases) page (or build it from source using `pnpm package:deb`), then install it with `apt` or `dpkg`:

```bash
# Install using apt (automatically resolves any missing system dependencies)
sudo apt install ./pubscript_0.1.0_amd64.deb

# Or install directly with dpkg
sudo dpkg -i pubscript_0.1.0_amd64.deb
```

Launch **PubScript** from your desktop application menu or from a terminal:

```bash
pubscript
```

- **Desktop Data Directory**: `~/.local/share/pubscript/` (contains `pubscript.sqlite` and persistent WebKit `IndexedDB` / `localStorage` data).
- **Uninstall**: `sudo apt remove pubscript`

---

### Option 2: Self-Hosted Docker Deployment (Recommended for Web & Multi-User)

A single container builds and serves the production web application, runs the Fastify REST + WebSocket API, and persists SQLite data on a mounted volume.

```bash
git clone https://github.com/Schwitzz/PubScript.git
cd PubScript
docker compose -f docker/compose.yaml up -d --build
```

- **Web App & API**: `http://localhost:8080`
- **Health Check**: `curl http://localhost:8080/api/health`
- **Persistent Data**: Stored in `./data/pubscript.sqlite` on the host.

#### Environment Variables (`docker/compose.yaml`)

| Variable | Default | Description |
|---|---|---|
| `PORT` | `8080` | HTTP port inside the container |
| `PUBSCRIPT_DB` | `/app/data/pubscript.sqlite` | Path to the SQLite database file |
| `PUBSCRIPT_ADMIN_EMAIL` | `admin@pubscript.local` | Bootstrap administrator email |
| `PUBSCRIPT_ORIGIN` | `http://localhost:8080` | Allowed CORS origin |
| `PUBSCRIPT_TOKEN_TTL` | `2592000` (30 days) | Session token lifetime in seconds |

---

### Option 3: Build & Run from Source

#### Prerequisites

- **Node.js** `>= 22`
- **pnpm** `9.15.9` (`corepack enable && corepack prepare pnpm@9.15.9 --activate`)
- Build tools for native SQLite/Argon2 bindings (`python3`, `make`, `g++`)
- *(Optional, for building the Linux `.deb` desktop package)*: `dpkg-deb`, `gcc`, `pkg-config`, `libgtk-3-dev`, `libwebkit2gtk-4.1-0`

#### 1. Install Dependencies

```bash
git clone https://github.com/Schwitzz/PubScript.git
cd PubScript
pnpm install --frozen-lockfile
```

#### 2. Run in Development Mode

Start the API server (`:8081`) and Vite web dev server (`:5173`):

```bash
# Terminal 1 — Fastify + SQLite API Server (port 8081)
PORT=8081 PUBSCRIPT_ORIGIN=http://localhost:5173 pnpm --filter @pubscript/server dev

# Terminal 2 — Vite React Web App (port 5173, proxies /api and /ws to :8081)
pnpm --filter @pubscript/web dev
```

Open **`http://localhost:5173`** in your browser.

#### 3. Build for Production

```bash
pnpm build
PORT=8080 pnpm --filter @pubscript/server start
```

When `apps/web/dist` is built, the server automatically serves both the production web bundle and the `/api` endpoints on `http://localhost:8080`.

#### 4. Compile the Native Linux `.deb` Desktop Package

```bash
pnpm package:deb
```

Produces `dist/pubscript_0.1.0_amd64.deb` (and `./pubscript_0.1.0_amd64.deb` in the repository root).

---

## Verification & Quality Gates

```bash
pnpm typecheck          # Strict TypeScript check across all workspace packages
pnpm test               # Unit & integration test suites across all packages
pnpm contract           # StorageAdapter contract suite (Local + Server parity)
pnpm lint               # ESLint across all packages
pnpm build              # Production bundle build
```

---

## Repository Layout

| Path | Description |
|---|---|
| `apps/web/` | React 19 + Vite application (Writing Studio, AI Sidebar, Characters, World, Plot, Whiteboard, Admin, Settings) |
| `packages/core/` | Shared domain types, ULIDs, token budgeting, backlinks, consistency engine, `StorageAdapter` contract |
| `packages/editor/` | TipTap 3 / ProseMirror schema, formatting extensions, node views, Markdown serializer, Hunspell spell & grammar services |
| `packages/ai/` | AI provider client, SSE streaming, token budget enforcement, Dexie/IndexedDB session store, suggestion & note builders |
| `packages/exporters/` | Deterministic manuscript exporters (`Markdown`, `HTML`, `EPUB`, `DOCX`, `ODT`, `PDF`) |
| `packages/ui/` | Design tokens, theme engine (`Ink`, `Parchment`, `Nocturne`, `Terminal`), density engine, UI component kit |
| `server/` | Fastify + SQLite multi-tenant API server, authentication, WebSocket sync, and admin routes |
| `desktop/` | Native Linux GTK3 + WebKit2GTK desktop wrapper (`pubscript-desktop.c`) and `.deb` packager (`build-deb.sh`) |
| `docker/` | Multi-stage `Dockerfile`, `compose.yaml`, and container entrypoint |
| `docs/` | Architecture & data model documentation (`DATA_MODEL.md`, `CONVENTIONS.md`) |

---

## License

Licensed under the **GNU General Public License v3.0** — see [LICENSE](./LICENSE) for details.