stilura 0.0.0-stage → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+Stilura (renamed from Litura) follows [semantic versioning](https://semver.org). Until 1.0 the minor number carries breaking changes.
+
+## Unreleased
+
+- Fixed cross-document Undo and saves from concurrent tabs. File writes now keep revision checks and history; workspace APIs reject symbolic links.
+- Desktop state survives server port changes. Closing, changing folders, and installing updates wait for confirmed saves. Partial brief answers survive reloads, and Save as falls back to a download where the system file-picker API is unavailable.
+
+- Renamed Litura → Stilura (*stilus*, the pen, + *litura*, the correction): npm package `stilura`, commands `stilura` / `stilura-mcp`, desktop app, skill (`skills/stilura`), and all user-facing strings. `STILURA_*` environment variables replace `LITURA_*` (old spellings still honored). The GitHub repo, release URLs, and the Tauri bundle identifier move with the name — reinstall the desktop app from the new releases page; its saved folder choice does not carry over. Browser drafts, `style.md`, and disk history (`.litura-history`, `litura:` storage keys, `<litura-edits>` tags) are untouched and keep working.
+
+## 0.6.0 — 2026-10-09
+
+- Litura now works alongside coding agents. `litura-mcp` (also `mcp-server.mjs`) is a stdio MCP server with seven tools — `draft_read`, `draft_write`, `review`, `rewrite`, `suggest`, `chat`, `idea` — that reuse the editor's own prompts; only `draft_write` changes anything, under the same revision guard as `PUT /draft`. A ready-made skill ships in `skills/litura/SKILL.md` with the voice rules, finding codes and the localhost API, for Codex CLI and Claude Code.
+- Continuations use their own suggestion model, chosen in Settings. It defaults to the cheapest authenticated model that writes well, with reasoning off; review, rewrites, chat and `/idea` keep the default model.
+- Settings offers ChatGPT Plus/Pro sign-in as an alternative to an API key, with a note that subscriptions count messages and automatic checks send many small requests.
+- The bubble's `Add to context` is now `Discuss`, matching the button on finding cards. After `Discuss` the paragraph `+` is available again: the passage stays selected, and that no longer hides it.
+- Markdown in the draft stays plain text: markers remain, dimmed, and what they mark is styled in place. Headings set bold, `**bold**`, `*italic*`, `_italic_` and `***both***` follow suit, `` `code` `` gets a quiet background, `[links](url)` an accent underline, `>` lines are muted, list markers dimmed and `---` carries a thin rule. Fenced blocks and inline code are left unparsed.
+- The draft sets larger (17px) on a 68-character measure. Margin notes are written in the draft's own italic, sit on the passage's baseline and open as a single line with no background. The conversation island now morphs its outline between the pill, the composer and a notice, notices are pill-sized and wait eight seconds (longer under the pointer), and `Suggesting…` shows in the folded pill instead of vanishing with the composer.
+- The paragraph `+` stands on the line under the pointer instead of a long paragraph's first line, stays up while a bubble is open, and on a paragraph that already has a note opens that note. The selection and Continue bubbles wait a beat (250 and 450 ms) and never appear if you type or click again first; every bubble fades in and out.
+- A margin note now stands on the line it was made at — its passage, or the line its `+` was pressed beside — instead of at the top of a long paragraph, and the `+` is no longer offered beside a line a note already covers. Retrying a failed draft load no longer duplicates the restored notes.
+- Notes in the margin no longer overlap: the rail cards were positioned relative to their normal place instead of the rail, and now also restack when a note grows. The conversation island sits 16px higher.
+- Experiment, Settings → While you write → Actions in the margin: `Note` and `Discuss` stand in the notes rail beside the selected line, and `Continue` sits right after the caret with its `⌘↵` hint, instead of floating over the text. Falls back to the floating bubble where there is no rail.
+- With a conversation open, the turns and the field now stand inside one opaque panel (near-black in dark mode) instead of floating over the draft, and the fade behind the island is gone. Notes in the margin no longer get cut at the header: the rail reaches the window top like the draft's lines do.
+- The text column now narrows (down to 52 characters) before margin notes give up their rail, so notes stay beside their lines on a 1100px pane instead of dropping into the chat.
+- The delete `×` on a margin note stands right after its last word instead of a box corner, and the paragraph `+` shows on a freshly loaded page without waiting for a resize.
+- A notice now takes over the whole island: the turns, finding cards and `×` above it are put away while it stands and come back when it goes, instead of hanging over an alert.
+- The draft no longer slides left when it grows past the window and a scrollbar appears (for instance when a note is added): the gutter is reserved on both edges.
+- Margin notes, slice 1: select a passage and press `Note` in the bubble to pin your own remark beside the line — plain text on the margin, no card chrome, blur commits and `Escape` drops, no Save/Cancel. Hover the empty margin beside a paragraph for its `+` (a paragraph note, never drifts); select all and press `Note` for the whole draft (pinned at the rail top, no mark). Notes stand in the margin rail on wide windows and stack in the chat stream on narrow ones. Create, edit, delete with Undo; notes persist per file. Notes go to the model with chat and rewrite requests as labeled scope context. No threads yet.
+
+## 0.5.0 — 2026-09-27
+
+- A file sidebar lists the `.md` and `.txt` files beside the draft, with a filter. Clicking one opens it; the previous text goes to History first. New, Open, Save as and History moved there from the header. The sidebar starts hidden.
+- `Save as new` uses the system save dialog.
+- Icons are now Tabler outline at a thinner stroke, resting dim and full on hover.
+- Provider errors such as an exceeded quota are shown as their message instead of raw JSON.
+- The chosen model survives restarts, even while it is missing from the current catalog.
+- The desktop app opens at once: it no longer fetches the model catalog on startup.
+
+## 0.4.2 — 2026-09-13
+
+- Clicking at the end of a paragraph now offers a Continue bubble, asking for the same continuation Cmd/Ctrl+Enter would. An explicit ask is allowed to open the next sentence and run longer than a background suggestion, instead of stopping at a finished thought.
+- Fixed the field popovers flashing at their previous position before snapping to the trigger.
+- Removed the unused standalone Rewrite button from the chat chip.
+
+## 0.4.0 — 2026-09-13
+
+- Added spell checking. Misspelled words are marked in the editor using a vendored en_US Hunspell dictionary, checked client-side alongside the existing style-tell markers.
+
+## 0.3.7 — 2026-09-13
+
+- Litura is now also a desktop app. A Tauri shell picks the writing folder, starts the same server on a free port, and shows it in its own window; it carries its own Node runtime, so nothing has to be installed first.
+- The review panel is one list again. Wording marks and review findings sat in separate sections repeating the same reason on every row; now they share a single list in document order, each row naming the passage and where the remark came from, with the reason on the card a click away. The header button says how many remarks are waiting instead of a bare number.
+- The desktop app updates itself: it asks GitHub on launch and from `Check for Updates…`, installs only what you accept and what its signing key verifies, and restarts. In that build the npm update switch is gone, since it would name a second, wrong way to update.
+
+## 0.3.6 — 2026-09-07
+
+- Published the latest editor interface and behavior updates together with the product audit and local draft history.
+
+## 0.3.5 — 2026-09-07
+
+- Refreshed the README preview with natural generic-writing highlights and meaningful rewrite options in a full-screen review flow.
+
+## 0.3.4 — 2026-09-07
+
+- Refreshed the README preview with a full-screen Litura review flow and three rewrite options.
+
+## 0.3.3 — 2026-09-07
+
+- Refreshed the README preview with a full-screen editor screenshot showing review marks and inline continuation.
+
+## 0.3.2 — 2026-09-07
+
+- Moved the Slop Score next to the settings control in the editor header.
+
+## 0.3.1 — 2026-09-07
+
+- The update badge now copies `npx litura-app` instead of opening a changelog, so the next update command is ready to paste.
+
+## 0.3.0 — 2026-09-07
+
+- Review remarks stay beside the passage they describe without shifting the draft when opened or clicked.
+- Added document actions and local history, replace-in-place previews, light/dark appearance settings, and automatic settings saves.
+- Refined the editor header, chat composer, settings controls, and release safety checks.
+
+## 0.2.0 — 2026-09-06
+
+- Settings can ask npm about new versions once a day, off by default. When a newer version is published the header shows a badge linking to this file; the badge links rather than installs, so updating stays a command you run. Left off, Litura opens no connection of its own.
+- Releases are cut by tag, with GitHub Actions running the checks and publishing over OIDC.
+
+## 0.1.0 — 2026-09-06
+
+First npm release, published as `litura-app`; the command it installs is `litura`.
+
+- Run from any folder with `npx litura-app`. The draft and the style guide are read from the folder Litura starts in, not from its install directory.
+- The browser opens on start, and a taken port falls through to the next free one.
+- `litura --version` and `litura --check-update` report the running and published versions. Litura opens no connection of its own.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vadim
+
+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.

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+<img src="public/logo-tile.png" alt="Stilura mark" width="72">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Stilura
+
+Your draft reads like a chatbot wrote it, and you can't say why. Stilura is a local editor that points at the exact phrases — "game-changing", "it's not just an app, it's a movement", the tidy list of three — names the pattern, and offers rewrites. Nothing in your text changes until you pick one.
+
+```bash
+npx stilura
+```
+
+![Stilura highlighting sales language, a "not X but Y" construction and a forced triple, with a finding card open](docs/screenshot.png)
+
+> **Renamed from Litura.** Same project, new name. The npm package moved from `litura-app` to `stilura` and the repository from `vadimchirkov/litura` to `vadimchirkov/stilura`. Your `draft.md` and other files stay where they are.
+
+## What it finds
+
+Each highlight carries a name and a reason, not a score. The patterns come from `style.md`, which you can edit: 20 of them, among them sales language, vague attribution ("studies show"), "not X but Y", forced triples, filler openers, stacked qualifiers, and generic positive endings. A second pass looks at structure: a buried point, a paragraph that breaks its opening promise, an abrupt topic shift.
+
+Click the count in the header for every remark in document order. `F8` and `Shift+F8` step between them. Disagree with one? `Keep as is` dismisses it for good.
+
+## You decide every change
+
+- `Options` on a finding gives three replace-in-place rewrites. Hover to preview, click to apply, `Try again` for three more.
+- `Discuss` opens a compact chat about the passage or the whole draft.
+- Short continuations appear below the line when you pause; `Tab` takes one, `Escape` drops it.
+
+The model suggests. It never edits the document on its own.
+
+## Rewrites that know the reader
+
+Before polishing, `/brief` asks four questions, one at a time: who reads this, what it should make them do, what they already know, and how much ground it covers. The answers travel with every rewrite, chat reply, and `/idea` expansion. Review never sees them, so it judges the prose unbiased.
+
+## Your text stays a file on your machine
+
+Run Stilura in the folder that holds your writing. It edits `draft.md` there and reads `style.md` next to it if one exists. The sidebar opens any other Markdown or text file in the folder. Nothing leaves the machine except what a model request sends to the provider you chose.
+
+## What it does not do
+
+- It does not tell you whether a text was written by AI. It names writing patterns.
+- It does not write the piece for you. Every passage it offers replaces one you already wrote.
+- Review and rewrites need a model provider: an API key, ChatGPT Plus/Pro sign-in, or credentials Pi already stores. The local wording count works without one.
+
+## Run
+
+### Command line
+
+```bash
+npx stilura
+```
+
+Needs Node.js 20 or newer. The browser opens on [http://127.0.0.1:3000](http://127.0.0.1:3000), or the next free port if that one is taken. Choose a provider and model under the gear button.
+
+### Desktop
+
+Download the build for your machine from [Releases](https://github.com/vadimchirkov/stilura/releases): `.dmg` on macOS, `.exe` on Windows, `.AppImage` or `.deb` on Linux. On first launch Stilura asks which folder holds your writing; `File → Open Folder…` picks a different one. It carries its own Node runtime and installs updates only when you say so.
+
+The macOS builds are not yet signed with an Apple Developer ID, so the first launch is refused: open `System Settings → Privacy & Security`, find Stilura near the bottom, and press `Open Anyway`. Once is enough.
+
+### Shortcuts
+
+`Cmd/Ctrl+K` attaches the selection or focuses the chat. `Cmd/Ctrl+Enter` asks for a continuation. `Cmd/Ctrl+S` downloads the draft; dropping a text file on the editor opens it. In the composer, `/` lists commands.
+
+## Data and storage
+
+The draft, findings, conversation, brief, and selected model live in browser local storage and survive a reload. Each file keeps its own copy, chat, findings, and brief. The draft is mirrored to its file on disk, so it survives cleared browser storage and opens in any editor. If the file changes underneath a running Stilura, it says so and offers to load it rather than merging or overwriting silently.
+
+The desktop app also saves these entries under its application data directory (`editor-state`), so changing the local server port does not reset them. Closing, changing folders, and installing an update wait for the editor to confirm the save; a save error keeps the app open.
+
+Stilura opens one connection of its own, and only to ask about new versions: to the npm registry if you switch that on in settings, or to GitHub when the desktop app starts.
+
+To work on Stilura itself:
+
+```bash
+git clone https://github.com/vadimchirkov/stilura.git
+cd stilura
+npm install
+npm start
+```
+
+## Updating
+
+The desktop app checks GitHub on launch and offers what it finds. Accepting downloads a bundle, verifies it against a signing key baked into the app, and restarts; declining changes nothing and the offer returns next launch. `Stilura → Check for Updates…` asks on demand. Because the app owns this, its settings have no npm update switch.
+
+On the command line, running `npx stilura` is the update: for a bare package name npm re-resolves the registry on every run, so each start picks up the latest release. The exceptions are a global install, which shadows that check and needs `npm i -g stilura`, and a clone, which needs `git pull`.
+
+```bash
+npx stilura --check-update
+```
+
+prints the published version next to the running one.
+
+Settings has an `Ask npm about new versions` switch, off by default. Turn it on and Stilura asks once a day and shows a badge in the header when a newer version is published; the badge links to the changelog rather than installing anything. Left off, Stilura opens no connection of its own.
+
+Releases are cut by tag: `npm version <patch|minor|major>`, then `git push` and `git push --tags`. GitHub Actions runs the checks, verifies the tag matches `package.json`, and publishes.
+
+An update leaves your draft, your `style.md`, and your model settings alone. Stored findings, chat history, and briefs are dropped only when a release changes their format.
+
+## Configuring
+
+Use the gear button to choose a provider, model, and reasoning level or to add an API key. Stilura also discovers credentials already stored by Pi and supported provider environment variables.
+
+Continuations use a separate suggestion model (same dialog, no reasoning
+control — the server always spends the least reasoning allowed). It defaults
+to the cheapest authenticated model that writes well and switches reasoning
+off; review, rewrites, chat, and `/idea` always use the default model above.
+
+The same dialog offers ChatGPT Plus/Pro sign-in as an alternative to an API
+key.
+
+Optional environment defaults:
+
+```bash
+PI_PROVIDER=anthropic
+PI_MODEL=claude-sonnet-4-6
+PI_THINKING_LEVEL=medium
+PORT=3000
+STYLE_FILE=./style.md
+DRAFT_FILE=./draft.md
+```
+
+Edit `style.md` to describe the voice, facts, and constraints Stilura should preserve. The file is read again for each model request, so changes apply without restarting the server.
+
+## Working alongside Codex / Claude Code
+
+Stilura pairs well with terminal agents on the same machine: the draft is a
+plain `draft.md`, and the server exposes the same operations the UI uses as
+local HTTP endpoints. If an external edit lands while Stilura runs, it never
+merges silently — it offers `Load disk` / `Keep mine` instead.
+
+A ready-made skill ships in `skills/stilura/SKILL.md` (also in the npm
+package): voice rules distilled from `style.md`, the finding-code taxonomy,
+and `curl` recipes for `GET/PUT /draft` and `POST /review /rewrite /suggest
+/chat` on `http://127.0.0.1:3000` (or the next free port up to 3010).
+Install it with:
+
+```bash
+cp -r skills/stilura ~/.codex/skills/   # Codex CLI
+cp -r skills/stilura ~/.claude/skills/  # Claude Code
+```
+
+then run the agent in the folder holding your draft while Stilura is running.
+Writes go through revision-checked `PUT /draft` (a stale revision returns
+`409` — re-read and retry once, never overwrite blindly).
+`/draft` always addresses the launch file. To work on another workspace file,
+use `?name=filename.md` on `/draft` and `/draft/history`; opening a file in one
+tab does not change another tab's save target. `GET /file?name=filename.md`
+also returns its revision. `PUT /file` requires that revision to replace a
+file; without one it only creates a missing file.
+
+### MCP server
+
+For agents that speak MCP (Codex CLI, Claude Code, ChatGPT desktop app),
+Stilura exposes the same operations as seven stdio tools — `draft_read`,
+`draft_write`, `review`, `rewrite`, `suggest`, `chat`, `idea` — in
+`mcp-server.mjs`, reusing the exact prompts the editor uses. Document
+arguments default to the live `draft.md`, so `review` with no arguments audits
+the current draft. Only `draft_write` changes anything, and it carries the
+same revision guard as `PUT /draft`. Start the server in the folder holding
+your draft (or set `DRAFT_FILE`), since the draft resolves against the
+server's working directory:
+
+```toml
+# Codex: ~/.codex/config.toml (or .codex/config.toml per project).
+# review/rewrite can run past the 60 s default tool timeout — raise it.
+[mcp_servers.stilura]
+command = "node"
+args = ["/path/to/stilura/mcp-server.mjs"]
+cwd = "/path/to/writing"
+tool_timeout_sec = 180
+```
+
+```bash
+# Claude Code (user scope; --scope project or .mcp.json for project scope)
+claude mcp add --scope user stilura -- node /path/to/stilura/mcp-server.mjs
+```
+
+Model credentials come from the same places as the editor: Pi's stored
+credentials (`~/.pi/agent/auth.json`) and provider environment variables.
+Per-call `agent` overrides accept `{ provider, model, thinkingLevel }`.
+
+## Development
+
+```bash
+npm run build
+npm run check
+```
+
+The server uses Node's native HTTP module. The browser UI is vanilla JavaScript with CodeMirror 6 and is bundled with esbuild. Source changes belong in `src/app.js`; `public/app.js` is generated.
+
+`npm run check:suggestions` tests insertion, cancellation and scheduling without model calls. `npm run eval:suggestions` makes real calls to the configured model using bilingual examples and records output and latency in `tmp/suggestion-evaluation.json`. See [the evaluation guide](docs/suggestion-evaluation.md) for review criteria and prompt/context experiments.
+
+The desktop shell needs a Rust toolchain and [Tauri's system dependencies](https://tauri.app/start/prerequisites/):
+
+```bash
+npm run desktop
+```
+
+That bundles the frontend, bundles the server into `dist/server.mjs`, downloads the Node runtime into `src-tauri/binaries/` (checksummed against the release, gitignored, ~120 MB), and opens the window. `npm run desktop:build` produces installers in `src-tauri/target/<triple>/release/bundle/`.
+
+Name the target when your Rust toolchain and the Tauri CLI disagree about the machine — an Intel `rustc` on Apple silicon, for instance, ends in a bundler looking for a sidecar nobody fetched:
+
+```bash
+npm run desktop:build -- --target aarch64-apple-darwin
+```
+
+After a build, `npm run smoke:desktop` starts the bundle against a throwaway folder and checks that it serves that folder's draft and gives the port back when the window dies. The UI needs no desktop build to test: it is the same page a browser gets from `npm run test:browser`, with `?shell=desktop` added to the URL for the desktop layout.
+
+Updates are signed with a minisign key that is not in this repository. CI reads it from the `TAURI_SIGNING_PRIVATE_KEY` and `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` secrets; the matching public key sits in `src-tauri/tauri.conf.json`, and an installed app refuses any bundle that key did not sign. Generate a new pair with `npx tauri signer generate` — and remember that replacing the public key strands every copy already installed.
+
+The app icon in `src-tauri/icons/` is generated from `public/logo-tile.png` (black mark on the cream tile) with `npx tauri icon public/logo-tile.png`. The mark also ships as `public/logo-mark.png` (transparency, light surfaces) and `public/logo-mark-white.png` (dark surfaces).
+
+See [SPEC.md](SPEC.md) for product behavior, API contracts, and implementation boundaries.
+
+## License
+
+[MIT](LICENSE)