inkhaven 1.2.7

Inkhaven — TUI literary work editor for Typst books
inkhaven-1.2.7 is not a library.

Inkhaven (blackInkhaven)

Inkhaven is a standalone terminal application for writing books and long-form technical documentation. It pairs a full-screen Typst editor with a local semantic index, an AI writing assistant, versioned snapshots, and a backup pipeline — so the entire writing workflow lives inside one binary, without leaving the terminal.

Your manuscript is organised as a hierarchy of .typ files (Book → Chapter → Subchapter → Paragraph), with first-class image (.png / .jpg / …), HJSON data (.hjson), and Bund script (.bund) leaves alongside paragraphs. Inkhaven stores metadata in a local DuckDB database, indexes every text node for full-text and semantic search, keeps versioned snapshots, embeds the Bund scripting language for hooks + custom rules, and streams answers from your chosen LLM provider — six are bundled (Gemini, Claude, OpenAI, DeepSeek, Grok, Ollama) and any model genai routes is one HJSON line away.

Inkhaven screenshot

Latest release · 1.2.7 — Polish + plumbing

Read the full notes: Documentation/RELEASE_NOTES/1.2.7.md

1.2.7 is a polish cycle on the timeline-heavy 1.2.6 release. Two themes carry the branch: timeline + ergonomics refinements on the user side, a large architecture rework on the source side (zero behavioural delta — verified post-hoc).

User-facing highlights:

  • Timeline polish. Tree-style two-level Tab/Enter navigation, Space track collapse with ▾/▸ glyphs, span-aware ↑/↓ event selection with viewport auto-pan, faint grid stripes, F12 book-wide critique inside the swim-lane view, per-book session persistence in .session.json, book-slug prefix on cross-book tracks (project overlay), and selection-aware Ctrl+V Shift+E for one-chord quick-event creation from any pane.
  • Ctrl+B U paragraph undelete. Single-slot kill-ring that round-trips body + tags + status + linked paragraphs
    • event timing after a Ctrl+D delete. New uuid; incoming wiki-links to the old id stay broken (status bar warns).
  • Alt+← / Alt+→ navigation history. Browser-style back / forward through every paragraph-open path — tree Enter, fuzzy picker, wiki-link follow, snapshot picker, timeline Enter, undelete. Plus Ctrl+V Shift+P recent-paragraph picker (32 entries, deduped).
  • Ctrl+Shift+M mouse-capture toggle. Flip terminal- native drag-select + system-clipboard copy on / off so you can grab snippets to paste elsewhere without routing through Ctrl+C chat-selection mode.
  • External-change auto-reload. Passive watcher on every autosave tick: clean buffer → silent reload, dirty buffer → red warning. CLI / sed / git pull / Bund scripts that touch the open paragraph file no longer leave stale text on screen.
  • Snapshot dedupe + today-widget colour + F8 from any pane. Three smaller refinements: F5 / autosave skip byte-identical snapshots, the today-words widget gets colour by goal progress, the typst-diagnostics modal works outside the editor pane.

Around those: 4 new tutorials (32 — 34) plus a "1.2.7 polish" section on tutorial 31; updated keybinding reference.

Under the hood — architecture rework

The TUI brain (src/tui/app.rs) went from a 26,605-LOC monolith to a 13,939-LOC central dispatcher with 21 sibling / child modules hanging off it. Every commit on the branch was byte-equivalent modulo visibility downgrades and import-path rewrites, verified post-hoc by a programmatic per-method diff (561 method bodies pre vs post; exactly one differed, and that turned out to be a pre-existing save_current bug that I fixed). 255 → 260 tests passing; zero build warnings.

The split makes the source navigable: render painters, modal state, AI orchestration, timeline navigation, tag picker, editor buffer methods, etc. each live in named files instead of being scattered across a single huge impl App {}. See src/tui/ for the layout.

Bugfix worth flagging

Ctrl+S in the editor was snapping the cursor to the beginning of the buffer on every save. Pre-existing since the 1.2.7 external-change auto-reload landed — save wrote the file but never restamped loaded_mtime, so the next tick saw the fresh mtime and reloaded the buffer (which resets the cursor). Fixed in this release. If you ever see that recurrence, file a bug.

Previous release · 1.2.6 — Tools for the working novelist

Read the full notes: Documentation/RELEASE_NOTES/1.2.6.md

1.2.6 is a wide-front release. Where 1.2.5 was one headline (in-process Typst), this one moves on six themes at once: tagging as project-wide metadata, diagnostics with an editor surface, AI as a writing partner (critique + memory + diff modal), labelled snapshots, a paragraph- mini story view, and a brand-new story timeline with calendar-aware events.

# Opt-in to the timeline (still 1.2.6+).
timeline: {
  enabled: true
  calendar: { preset: "gregorian" }    # or "sols" or "custom"
}

# Opt into the diff modal on AI rewrites (default already on).
ai: {
  per_paragraph_memory: true   # default false
  diff_review_on_apply: true   # default true
}

Headlines from 1.2.6:

  • Tagging stack. Ctrl+B ] picker · Ctrl+B } project search · R rename project-wide · inkhaven export --tag filter · tree-pane #tag pips · five ink.tag.* Bund words · Scrivener keyword import.
  • Diagnostic UX. Red ● in the gutter for every line with a parse / semantic error · F8 diagnostics list · Ctrl+V N / Shift+N navigate · Ctrl+F12 AI explain the diagnostic at cursor (was F11; macOS grabs F11).
  • AI as a partner. F12 mode-aware critique (critique-edit plain / critique-changes split-edit) · per-paragraph memory (ai.per_paragraph_memory: true) · side-by-side diff modal before any r / g apply · smart marker extraction across model dialects.
  • Snapshot annotations. F5 pops a one-line prompt; F6 picker shows annotations as italic-cyan ✎ lines beneath each row.
  • Story view split. Ctrl+V w (lowercase) for the paragraph mini view; Ctrl+V Shift+W for the book. New Bund word ink.story.render writes the graph to PNG from a script.
  • Render preview live zoom. + / - zoom in Ctrl+V R; 0 resets; cursor column anchored.
  • 🌟 Story timeline. Calendar-aware events (gregorian / sols / custom), inkhaven event add/list/show CLI, Ctrl+V e picker, Ctrl+V t swim-lane view with scope navigation (u / d / b / p), AI health critique (y / Y / Ctrl+Y), seven ink.event.* Bund words + two new hooks (hook.on_event_added / hook.on_event_orphaned). Opt-in via timeline.enabled.

The companion Book of Inkhaven at Book/ covers all of 1.2.6 in print form. It stays synced to 1.2.6 until the next major release; 1.2.7 polish lives in the tutorials.

Previous release · 1.2.5

typst_compile: { engine: "inprocess" }

Flip it and Inkhaven stops shelling out to the host's typst binary for builds. The full compiler — typst + typst-pdf + typst-kit (fonts + @preview packages) — is linked into every 1.2.5+ binary and runs inside the inkhaven process. The external CLI stays the default; the switch is a runtime decision.

Around that one switch:

  • In-process compile engine. typst::compile + typst-pdf runs on a worker thread; the foreground TUI keeps the spinner animated. Bundled Computer Modern + Linux Libertine fonts ship in the binary; system fonts are also searched. @preview/<pkg> imports fetch + cache via typst-kit. Hermetic mode (no system fonts, no package fetch) lives behind two HJSON booleans.
  • Parse diagnostics on save / idle. typst-syntax re- parses the open paragraph on every save and every diagnostics_idle_seconds of editor idle. First parse error lands on the status bar with line L:C — <message>. Engine-independent — works in both external and inprocess.
  • Semantic diagnostics (opt-in). When semantic_diagnostics: true AND engine = "inprocess", a full compile runs after parse passes. Surfaces unknown functions, type errors, missing fonts. False positives expected for paragraphs that depend on book-level definitions — leave off for preamble-heavy manuscripts.
  • Ctrl+V N — diagnostic navigation. Jump the editor cursor to the next typst diagnostic (parse or semantic). Wraps. Status bar reports diag 2/5 line 12:5 — <message>.
  • Ctrl+V R — render paragraph preview. Saves the buffer, rasterises every page in-process via typst-render, floats the PNG on top of the editor. ← / → navigate pages, S saves the current page at full DPI, A saves every page as <base>-page-NNN.png. Esc closes back to the editor (cancelling the save picker preserves navigation state).
  • TUI-friendly compiles. Compile splash shows the active engine line (internal · fonts: bundled + system · @preview: on or external · /usr/local/bin/typst). Esc cancels in-flight compiles — external sends SIGTERM, in-process abandons the worker (it finishes in the background). Ctrl+B A / B / O now autosave the primary editor (and the secondary editor in similar-paragraph mode) before walking .typ files.
  • inkhaven doctor. New CLI — prints a health report with engine summary, typst path, font + package counts, cache size, and (when run inside an initialised project) hierarchy shape + word counts. Notes section calls out actionable warnings like typst NOT on PATH. Pipe- friendly.
  • Embedded logo in credits pane. include_bytes! embeds logo.png in the binary; Ctrl+B V banners it above the version + dependency list.
  • Project-wide node tagging. Three entry points, one tag namespace stored as Node.tags: Vec<String>: Ctrl+B ] opens the floating tag picker for the open paragraph (Space multi-selects, T applies, A adds a new tag, D deletes a tag project-wide with a blast- radius confirm); Ctrl+B } opens the same picker in search mode — Enter on a tag lists every paragraph that carries it, with a typeable filter, and Enter on a hit opens it; g in the tree pane runs the picker against the marked set (or the cursor row), bulk-tagging a whole selection in one go. Editor T returns focus to the editor; tree g stays in the tree.
  • Story view — Ctrl+V W. Twopi-style radial graph of the current book: book at the centre, each structural depth on a concentric ring with sibling wedges sized by subtree leaf count. Different SVG shape per node kind (folder / box / octagon / ellipse / note / parallelogram / chevron / egg / diamond / hexagon); long titles wrap to multiple lines and node boxes scale to fit. Solid grey edges for the structural skeleton, dashed purple for linked_paragraphs wiki-links, dashed green from Characters / Places / Artefacts to the paragraphs that mention them. Rasterised via resvg + tiny-skia, displayed via ratatui-image. S saves the PNG.
  • New tutorial: Typst in-process — engine switch, fonts, packages, diagnostics, render preview, doctor.

Every prior release lives under Documentation/RELEASE_NOTES/.

Why Inkhaven

  • Terminal-first. Inkhaven runs over SSH, in tmux, on a tiling WM — no browser, no Electron. The TUI uses ratatui and tui-textarea.
  • Your manuscript is plain files. A paragraph lives in a .typ file on disk; the metadata database tracks hierarchy and search but the prose is text — you can read it, diff it, version-control it, and edit it with another tool any time.
  • Semantic search out of the box. Embeddings via fastembed and HNSW are computed locally. Search for "the moment the lighthouse fails" and find the paragraph even if it never uses those exact words.
  • AI is a co-author you steer. Inferences stream live; you control the scope (selection / paragraph / subchapter / chapter / book), the mode (Local-only RAG vs. Full general knowledge), and the destination (replace, insert, top, bottom, copy, grammar-apply). Inkhaven does NOT provide inherent privacy when external providers (Gemini / Claude / OpenAI / DeepSeek / Grok) are used — prompts travel to their servers under their terms. For privacy, set llm.default_provider: "ollama" and run a local model; every other inkhaven subsystem (RAG embedding, semantic search, snapshot diff) is already on-device.
  • Multilingual. Snowball stemmers and multilingual embeddings make Russian, German, French, Spanish, Italian and others first-class. The shipped defaults cover English and Russian.
  • Help, characters, places, artefacts, scripts — built in. Nine system books are seeded on every project: Notes, Research, Prompts, Places, Characters, Artefacts, Typst, Scripts, Help. Mentions of names from the lexicon books light up in the editor (cyan / amber / peach / underline). Ctrl+B P / C / Y / G query each via RAG. F1 answers questions about Inkhaven itself by RAG over Help. Scripts (added in 1.2) holds .bund source files auto-loaded into the embedded Bund scripting VM at project open — see Documentation/Bund/.
  • First-class images. Drop PNG / JPG / WebP / SVG into the tree; Book assembly emits the right wrap_image_* calls and ships the bytes into the typst tree. Ctrl+B P inside #image("…") opens a sibling picker. Enter on an Image row pops a ratatui-image preview (kitty / sixel / iterm2 / half-block).
  • From buffer to PDF in two chords. Ctrl+B A assembles your tree into a typst-compilable directory; Ctrl+B B compiles it; Ctrl+B O builds and copies the PDF into your shell's cwd as <book>-YYYYDDMM-HHMM.pdf. Compile failures route the captured stderr into a fresh AI chat with a typst-aware system prompt.

Features at a glance

Editor

  • Typst syntax highlighting via tree-sitter-typst.
  • Regex find / replace with same-line current-match highlighting.
  • Split-edit with versioned snapshots — see two versions of a paragraph side by side, accept either.
  • Word-aware navigation and deletion shortcuts.
  • Vertical block selection (Alt+arrows) with rectangular copy.
  • System-clipboard cut / copy / paste, plus per-doc undo / redo.
  • Live "changes since last save" bolding; grammar-correction highlights what changed after a g apply.

Tree

  • Multi-level folding (← / → / Z / X).
  • Per-kind row colours (book / chapter / subchapter / paragraph / image)
    • open-paragraph marker.
  • Plain-letter shortcuts for add (B/C/V/A/S/+/P), delete (D/-), reorder (U/J).
  • Document status badge column — one character per row colour- coded to the workflow stage (n / 1 / 2 / 3 / F / R).
  • Mouse: click to focus + select; scroll wheel scrolls.

AI pane

  • Streaming markdown rendering — bold / italic / headings / code / lists.
  • Six scope modes (cycled by F9): None, Selection, Paragraph, Subchapter, Chapter, Book — each prepends the matching content to the next prompt.
  • Two inference modes (F10): Local (use only supplied context) and Full (augment with general knowledge). Help inferences are pinned to Local automatically.
  • Persistent chat history with one-key clear (Ctrl+B C).
  • Full-screen AI layout (Ctrl+B K) — AI pane + scrollable chat history + AI prompt; persisted to .inkhaven-chat.json between sessions; Ctrl+F searches; Ctrl+C enters a turn-selection mode.
  • Lexicon RAG — Ctrl+B P / C / G / Y in the editor sweep the selection through Places / Characters / Notes / Artefacts and prepend the lookup to the next AI prompt.
  • F1 Help-manual floating query → grounded answer over the Help book. inkhaven import-typst-help seeds Help with a curated typst reference.
  • F7 Grammar check with deterministic correction extraction (g replaces the buffer with just the corrected text, preserving Typst markup).

Storage and backup

  • DuckDB metadata + Tantivy full-text + HNSW vectors via bdslib.
  • Snapshots: F5 captures the buffer; F6 opens the snapshot history picker.
  • inkhaven backup --out <dir> zips the entire project.
  • inkhaven restore <archive> --to <dir> puts it back.
  • Auto-backup on TUI exit when the last backup is older than backup.max_age (humantime: 7d, 12h, 30m, …) — splash screen with a progress bar.
  • Session persistence: cursor position, focus, tree-scroll, open paragraph all survive restarts. Per-paragraph cursor memory: switch around and every paragraph remembers where you were.

CLI tools

  • init — set up a fresh project (interactive confirmation if the directory exists).
  • add / delete / mv / list — manage the hierarchy from a script.
  • search "phrase" — semantic search from the shell.
  • reindex — re-walk .typ files into the database.
  • export typst / export pdf — produce a single Typst manuscript or a built PDF.
  • import-help --documents-directory <dir> — populate the Help book from a directory of markdown / text / typst files (wipes Help first).
  • backup / restore — see above.
  • ai "prompt" — one-shot inference from the shell (no TUI).

Configuration

A single inkhaven.hjson in each project root drives every knob: embedding model, LLM providers, autosave cadence, sync interval, hierarchy depth, language, snowball stemmers, the full visual theme (per-pane backgrounds and foregrounds, all syntax colours, lexicon highlight colours), key bindings, and backup policy.

Install

Inkhaven ships as a single static binary per platform. Three install paths:

1. cargo binstall (no compile)

If you already have cargo-binstall:

cargo binstall inkhaven

cargo-binstall reads [package.metadata.binstall] from Cargo.toml, picks the right asset off GitHub Releases, and drops the binary into ~/.cargo/bin. Works on Linux (x86_64), macOS (Intel + Apple Silicon), and Windows (x86_64).

2. GitHub Releases (direct download)

Grab the tarball for your platform from Releases, unpack, and put inkhaven somewhere on your PATH. Builds are produced by the release.yml workflow on every tag push.

3. cargo install --git (compile from source)

cargo install --git https://github.com/vulogov/blackInkhaven --tag v1.0.0

This works because every dependency (including bdslib and tree-sitter-typst) is vendored under vendor/ — no separate registry fetches, no GitHub auth needed. The first build takes ~10 minutes on a modern laptop because of DuckDB + Tantivy + fastembed compilation; the release binary above is the fast path.

Inkhaven is not published on crates.io. See Cargo.toml's publish = false line and the Documentation/ notes for the rationale.

Quick start

# Build (if installing from source)
cargo build --release

# Initialise a project (asks for confirmation if the directory exists)
./target/release/inkhaven init ~/Books/my-novel

# Build the hierarchy from the CLI…
./target/release/inkhaven --project ~/Books/my-novel add book "My Novel"
./target/release/inkhaven --project ~/Books/my-novel \
    add chapter "The Beginning" --parent my-novel
./target/release/inkhaven --project ~/Books/my-novel \
    add paragraph "Opening Scene" --parent my-novel/the-beginning

# …or skip the CLI and add everything from the TUI
./target/release/inkhaven --project ~/Books/my-novel
# Inside the TUI: B (book), C/V (chapter), A/S (subchapter), +/P (paragraph)

Use cases

  • Long-form fiction. Hierarchy fits novels naturally (Book → Part → Chapter → Scene). Places / Characters / Research system books keep worldbuilding next to prose.
  • Technical documentation. Each chapter is a .typ file; the tree doubles as a table of contents. Semantic search makes "where did I document the retry policy?" a one-keystroke question.
  • Translation work. Multilingual embeddings + per-language Snowball stemmers let you keep source and target in two parallel books.
  • Research notebooks. Snapshots track how a draft evolved; the AI pane can summarise a chapter when you come back after a week.
  • Help and onboarding writing. Ship docs as a directory and let Inkhaven build a Help book your readers can query through F1.

Documentation

The full docs live under Documentation/.

Start here:

Reference:

Built with

Licence

Apache 2.0 — see LICENSE.