proseview 0.1.0__tar.gz

proseview-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ari Saif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proseview-0.1.0/PKG-INFO

@@ -0,0 +1,376 @@
+Metadata-Version: 2.4
+Name: proseview
+Version: 0.1.0
+Summary: A local dashboard and AI harness for Markdown-first novel repositories.
+Author: Ari Saif
+License: MIT
+Project-URL: Homepage, https://github.com/ourarash/proseview
+Project-URL: Source, https://github.com/ourarash/proseview
+Project-URL: Issues, https://github.com/ourarash/proseview/issues
+Keywords: writing,novel,markdown,dashboard,lexical-analysis,prose
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Jinja2>=3.1
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: e2e
+Requires-Dist: pytest>=7; extra == "e2e"
+Requires-Dist: playwright>=1.44; extra == "e2e"
+Requires-Dist: pytest-playwright>=0.5; extra == "e2e"
+Dynamic: license-file
+
+# Proseview
+
+> A local dashboard and AI harness for novelists who write in Markdown. ✍️
+
+Proseview reads your manuscript folder, gives you a writer-grade view of
+its structure and prose, and turns the same surface into a place where you
+can read, edit, annotate, and bring an AI assistant to any paragraph
+without leaving the page.
+
+It runs entirely on your machine. No cloud, no telemetry, no lock-in. Your
+files stay where they are.
+
+[![CI](https://github.com/ourarash/proseview/actions/workflows/ci.yml/badge.svg)](https://github.com/ourarash/proseview/actions/workflows/ci.yml)
+![status](https://img.shields.io/badge/status-alpha-orange)
+![python](https://img.shields.io/badge/python-3.11%2B-blue)
+![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)
+![license](https://img.shields.io/badge/license-MIT-green)
+
+![The Proseview dashboard: word-count goal, writing streak, and recently modified files](docs/images/dashboard.png)
+
+## 📸 A look around
+
+### Read and revise, with editorial passes on
+
+Nine prose passes highlight repetition, passive voice, filter verbs and more,
+right on the page you are reading.
+
+![A scene open in the reading view with four highlight passes enabled](docs/images/scene-highlights.png)
+
+### Search the whole repository
+
+`Mod-K` from anywhere. File paths, scene metadata, TODOs, notes, and prose,
+grouped by kind.
+
+![The search palette open over a scene, showing file, scene, and prose matches](docs/images/search.png)
+
+### Analytics that mean something
+
+![Character presence, sentence-rhythm bands, setting stickiness, and character co-occurrence charts](docs/images/analytics.png)
+
+> Screenshots use the bundled `fixtures/demo-repo` (four scenes), so the charts
+> are deliberately small. Your book fills them in.
+
+## ✨ What you get
+
+- 📊 **Dashboard.** Word count, chapter pacing, lexical health (MATTR /
+  MTLD), sentence-rhythm variance, character presence, location
+  stickiness, character co-occurrence, plus a sortable scene table.
+- 📖 **Reading view.** Open a scene as a typographic page with a real
+  reader font. The dashboard chrome gets out of the way.
+- ✏️ **WYSIWYG editor.** ProseMirror-backed. Same surface as the reading
+  view, just with `Edit` toggled on. Mod-S saves. Conflict guard checks
+  the file mtime so a concurrent change in your editor never gets
+  silently overwritten.
+- 🎨 **Editorial highlights.** Toggle nine prose passes on top of any
+  scene: repetition, passive voice, filter verbs, crutch words,
+  hyperbole, lyrical reach, sensory density, comedy beats, first-person
+  rate. Each pass is a single click.
+- 🗒️ **Inline TODOs and Notes.** Select a passage, drop a `TODO` or a
+  tagged `NOTE` (continuity / character / theme / question), and it
+  lands in the file as a Markdown comment. Survives in git.
+- 🤖 **AI on the selection.** Send the highlighted passage to Codex,
+  Claude, or Gemini in one click. An in-browser terminal hosts the
+  conversation; the agent can see the file, the selection, and your
+  repo. Your tools, your prompts.
+- 💬 **Discuss with Codex.** Open a document-aware conversation beside
+  any scene or supported repository text file. Proseview sends the current
+  document automatically and only adds selections, files, or folders you
+  explicitly attach. Safe progress summaries, plans, tool activity, approval
+  requests, and streamed answers stay visible while you read.
+- 🧰 **In-browser terminal.** xterm.js wired to a real PTY. Run `codex`,
+  `claude`, or any shell command without leaving the dashboard. Tabs
+  persist across page reloads.
+- 🔁 **Live reload.** Save a file in your editor and the dashboard
+  picks up the change over Server-Sent Events. No manual refresh.
+- 🔗 **Deep links.** Every scene and file has a URL. Copy the address
+  bar to share or revisit a view. Back / forward work.
+- 🔎 **Repository search.** Press Mod-K or choose Search from any dashboard,
+  scene, or file view. File paths come from one repository-wide inventory;
+  opening a result loads its preview lazily and reopening Search preserves the
+  current query.
+- 🎨 **Themes and fonts.** Light, Dark, Docsify, Hopscotch. Reader,
+  Literary, Inter, Georgia, Baskerville, Sans, Mono.
+- 🧪 **Tested.** 400 tests: unit coverage of the analytics engine, scene
+  parsing, save guards, history, and refresh behavior, plus end-to-end
+  tiers that boot the real server and drive the real UI in a browser.
+
+## 🚀 Quick start
+
+**Requirements:** Python 3.11+ on macOS or Linux. The server uses Unix-only
+APIs (`fcntl`, and a real PTY for the terminal), so Windows needs WSL.
+
+```bash
+git clone https://github.com/ourarash/proseview.git
+cd proseview
+pip install -r requirements.txt
+
+# Run the dashboard against your novel repo
+python -m proseview --root /path/to/your/novel
+```
+
+A browser tab will open at `http://localhost:7842`. Press Ctrl-C to stop.
+
+If you'd rather install proseview as a tool:
+
+```bash
+pip install -e .
+proseview --root /path/to/your/novel
+```
+
+## 📁 What proseview expects
+
+A folder of Markdown scene files, one folder per chapter. The minimum
+viable repo:
+
+```text
+my-novel/
+├── manuscript/
+│   ├── ch01/
+│   │   ├── 01-opening.md
+│   │   └── 02-meeting.md
+│   └── ch02/
+│       └── 01-aftermath.md
+└── .proseview.yaml          # optional
+```
+
+Scene files use simple frontmatter:
+
+```markdown
+---
+title: Opening
+chapter: Chapter 1
+status: draft
+where: A bar in the West Village
+when: Friday night, late
+pov: Nima
+characters: [Nima, Mira]
+goal: Nima needs to get the question on the table
+conflict: He's afraid she already has someone
+outcome: She agrees to dinner; he leaves rattled
+todos:
+  - Tighten the opening paragraph
+---
+
+# Opening
+
+The bar was loud and the music was bad...
+```
+
+Every field is optional. Proseview reads what's there and falls back
+gracefully on what isn't.
+
+### 📝 Frontmatter contract
+
+These are the keys proseview recognizes. Any other keys are passed
+through and ignored. Every field is optional.
+
+#### Identity
+
+- `title` (string) header of the scene viewer; defaults to a Title-Case
+  version of the filename stem.
+- `chapter` (string) "Chapter" column in the scene table and the
+  chapter rows of charts; defaults to the chapter folder name.
+- `status` (string) color-coded status badge. Conventional values:
+  `draft`, `revision`, `done`. Anything else renders as a generic chip;
+  missing means `unknown`.
+
+#### Scene context
+
+- `where` (string) "Where" row in the scene card. Also feeds the
+  **Setting Stickiness** chart (Words per Location).
+- `location` (string) synonym for `where` (older convention).
+- `when` (string) "When" row in the scene card. Free-form.
+- `pov` (string) "POV" row in the scene card. Free-form.
+- `characters` (list of strings) "Characters" row in the scene card;
+  each name is clickable to open the bio if
+  `<characters_path>/<name>.md` exists. Also feeds the **Character
+  Presence** and **Co-occurrence** charts.
+
+#### Arc
+
+- `goal` (string) "Goal" row in the arc panel.
+- `conflict` (string) "Conflict" row in the arc panel.
+- `outcome` (string) "Outcome" row in the arc panel.
+
+#### Tasks
+
+- `todos` (list of strings) each entry shows up as a frontmatter-level
+  TODO in the Tasks panel. Inline `<!-- TODO: ... -->` comments inside
+  the prose are picked up too and get a line anchor.
+
+A scene with no frontmatter still renders, just with `Unknown` /
+`Not defined` placeholders in the scene card and the file's stem as
+its title.
+
+## ⚙️ Configuration
+
+`proseview` works with zero config. Drop a `.proseview.yaml` at the
+repo root if you want to customize:
+
+```yaml
+# Where the manuscript lives. Default: manuscript/
+manuscript_path: manuscript/
+
+# Where character bios live. Default: story-bible/characters
+characters_path: story-bible/characters
+
+# Where AI skill prompts live. Default: skills
+skills_path: skills
+
+# Word-count goal for the finished book.
+target_words: 80000
+
+# Daily word goal (drives the "days to finish" estimate).
+daily_target: 500
+
+# Healthy band for local lexical variety (MATTR).
+mattr_band: [0.74, 0.77]
+
+# Healthy band for whole-scene lexical variety (MTLD).
+mtld_band: [105, 130]
+
+# Editor URL handler. One of: vscode, cursor, zed, positron, custom.
+editor:
+  scheme: vscode
+
+# Folders shown in the file tree alongside the manuscript.
+repo_tab:
+  folders: [plans, continuity, outline, story-bible, docs, templates]
+```
+
+Every key has a sensible default; missing folders are simply skipped.
+
+## 🧠 The analytics
+
+Lexical health is real, not vibes:
+
+- 📐 **MATTR** (moving-average type-token ratio, window 100). Measures
+  *local* vocabulary variety. Low = the same words inside a paragraph;
+  high = constant rotation that may feel jittery.
+- 📐 **MTLD** (measure of textual lexical diversity). Measures
+  *whole-scene* variety. Low = the scene keeps circling the same ground;
+  high = the scene keeps reaching.
+- 📐 **Sentence rhythm.** Per-chapter standard deviation of sentence
+  length. Static / Rhythmic / Dynamic zones are annotated on the chart.
+- 📐 **Dialogue percentage**, **passive voice rate**, **crutch-word rate**,
+  **first-person density**, **sensory density**, **filter-verb rate**,
+  **paragraph length**.
+
+Every scene gets a row in the deep-dive table; outliers get listed under
+Editorial Alerts with a one-line revision signal.
+
+## 🤝 Working with AI
+
+Four places where AI shows up, all opt-in:
+
+1. **Selection menu.** Highlight any text in a scene. The pill that
+   appears includes `Add TODO`, `Add Note`, and (if the corresponding
+   tools are installed locally) `Run in Codex` and `Skills`. Skills are
+   reusable prompts you keep in `skills/<name>/SKILL.md`; they show up
+   automatically in the menu.
+2. **Agent menu.** From the scene header, launch a conversation with
+   Codex, Claude, or Gemini scoped to that file. The conversation runs
+   in the in-browser terminal so you can keep reading the prose
+   underneath while the agent works.
+3. **Discuss.** Choose `Discuss` in a scene or text-file header for a
+   document-aware conversation in the side dock. The document you are
+   reading is attached to each question by default — drop its chip to omit
+   it, or press `@` to attach other files and folders. Tool and file
+   actions wait on approvals you can see.
+
+   Under the hood it starts a local `codex app-server` on demand and uses
+   your existing Codex login, model, and history. Proseview stores a bounded
+   list of thread IDs and display metadata for each document in your state
+   directory, and discards raw reasoning — only Codex's own progress summaries
+   reach the browser. `History` lets you reopen, rename, export, or remove a
+   previous conversation. `New conversation` starts a blank discussion while
+   keeping the previous one available there.
+4. **TODOs as Markdown.** Every TODO and Note is a plain
+   `<!-- TODO: ... -->` or `<!-- NOTE[tag]: ... -->` comment in the
+   scene file. Your AI assistant can see them through the file, your
+   repo can track them through git, and you can grep them.
+
+## 🛣️ Roadmap
+
+This is alpha. Things that are working and things that are coming:
+
+- ✅ Live server, live reload, ProseMirror editor, highlights, TODOs,
+  notes, deep links, in-browser terminal, agent menu, and document-aware
+  Discuss conversations with Codex.
+- ✅ Vendored front-end dependencies. chart.js, marked, xterm and
+  friends ship with the package and load from `/vendor/`. ProseMirror
+  modules are pinned to specific versions on esm.sh.
+- ✅ Modularized front-end. The JS lives in twelve topical files under
+  `templates/assets/js/`, concatenated at render time.
+- ✅ `proseview init` writes a starter `.proseview.yaml` so a fresh
+  novel repo gets a working configuration with one command.
+- ✅ Persisted UI prefs. Your highlight-pass toggles and theme choices
+  survive scene navigation and reloads.
+- 🚧 Diff-confirm for AI-suggested edits (selection runs in a terminal
+  today; nothing applies edits without your approval, but the diff UX
+  is still terminal-only).
+- 🚧 Configurable agent list (Codex / Claude / Gemini are presets today).
+- 🚧 Continuity surfacing (warn when a scene contradicts a known fact).
+- 🚧 Frontmatter editor (status, where, todos) inside the scene viewer
+  so you don't need to drop into your text editor for routine fields.
+
+See [plans/roadmap.md](plans/roadmap.md) for the full punch list.
+
+## 🧪 Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+That runs the unit suite plus an HTTP end-to-end tier that boots a real
+`proseview` subprocess and drives every endpoint — saves and the conflict
+guard, TODOs and notes, the AI proposal bridge through the actual CLI, live
+reload over SSE, and PTY terminals — asserting on bytes written to disk.
+Discuss integration tests use a deterministic fake app-server and isolated
+home/state directories; they never contact Codex, the network, or your profile.
+~15 seconds, no extra dependencies.
+
+A browser tier drives the real UI in Chromium (editor round-trip fidelity,
+the selection menu, highlight passes, deep links, agents, terminals, Discuss
+streaming/approvals/shared-dock behavior, and applying an AI proposal end to
+end). It's opt-in:
+
+```bash
+pip install -e ".[e2e]"
+python -m playwright install chromium
+pytest -m e2e_browser
+```
+
+Both tiers work on a throwaway copy of `fixtures/demo-repo`. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## 📜 License
+
+MIT. See [LICENSE](LICENSE).