PubScript/README.md

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 page (or build it from source using pnpm package:deb), then install it with apt or dpkg:

# 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:

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.

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

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):

# 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

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

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

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 for details.