ductus

ductus is a Helix-style terminal editor. This glossary fixes the words that code, docs, and conversations use for its domain.

Text

Document: The text of one file as the editor holds it, together with its Line ending and Revision tree. Avoid: Buffer, file

Grapheme: The smallest unit of text a user sees as one character, such as a letter with its combining marks or a ZWJ emoji. One invalid byte is one Grapheme. Avoid: Character, except in a command name such as move-character-left; glyph

Hunk: One run of lines that differ between an old and a new text: lines added, removed, or changed, with at least one equal line between two Hunks. Avoid: Chunk, change, delta

Line ending: The byte sequence that ends a line in a Document, either LF or CRLF. Avoid: Newline style, EOL

Position: A byte offset into a Document. Char, line, and UTF-16 offsets are derived from it. Avoid: Index, cursor position

Editing

Block mode: The Mode that keeps a block: the rectangle between two corners, the anchor corner and the cursor corner. Each line of the block that reaches its left side gets one Range. A motion moves the cursor corner, and the Ranges follow the block. Most other keys of Select mode act on the Ranges, and then the editor goes back to Normal mode. Avoid: Visual block, column mode, rectangle selection

Jump: A place to go back to: a Document and the Selection in it. An edit moves a Jump with its text. Avoid: Mark, bookmark, location

Jumplist: The Jumps of one View, oldest first, that C-o steps back through and C-i steps forward through. A command that moves far, such as gg or gd, adds the place it leaves. Avoid: History, back stack

Mode: The state of the editor that decides what a key does: Normal, Insert, Select, or Block mode. Each Mode has its own table of keys. Avoid: State, layer

Range: One anchor and head pair of Positions. The anchor stays put and the head moves. A Range always covers at least one Grapheme. Avoid: Cursor, region

Register: A named store of text values, one value for each Range, that a yank writes and a paste reads, such as ", the default, or +, the system clipboard. Avoid: Buffer, kill ring

Selection: The sorted, non-overlapping set of Ranges on one (Document, View) pair, with one Range marked primary. Avoid: Cursors, multi-cursor

Tab page: A set of Views that fill the screen together, and the View of the set that has the focus. Only one Tab page shows at a time. A Document belongs to no Tab page, so Views of two Tab pages can show the same Document. Avoid: Tab, except in a command name such as goto-next-tab; workspace, layout

Text object: A part of the text around a Range that a key names, such as a word, a pair of brackets, or a function, which a command selects inside or around. Avoid: Object, motion

Transaction: A set of changes to a Document, checked against the length of the Document it applies to. Avoid: Edit, patch, diff

View: One window onto a Document, with its own Selection and scroll position. Views share the screen, side by side or one above the other. Splitting a View adds a second View onto the same Document. Avoid: Pane, split, window

Rendering

Annotation: Text that a View draws next to or over a Document but that is not in the Document, anchored to a Position and mapped through each Transaction. Avoid: Ghost text, virtual text, decoration

Diff session: Two Views whose Documents are compared line by line, with their rows lined up so that each equal line is on the same row in both Views. Avoid: Diff mode, diff view

Grammar: A tree-sitter parser for one language, fetched from a source pinned to one commit, or read from a directory of the user, and built into a shared object that dk loads to highlight a Document. Avoid: Parser, syntax, language

Highlight query: A tree-sitter query, highlights.scm in Helix format, that names a Style scope for each node of a Grammar that it captures. Avoid: Syntax file, highlight rules

Picker: A box that lists items, such as files, Documents, or commands, filters them by a query that the user types, and acts on the item that the user picks. Avoid: Finder, fuzzy finder

Popup: A box next to the cursor of the focused View that shows text from a Language server, such as hover text or signature help, one entry at a time. It does not take the focus: a key that it does not use goes to the editor. Avoid: Tooltip, overlay, window

Style scope: A Helix theme key, such as ui.text or ui.statusline, that a draw call looks up to get its style. A missing scope falls back to its parent. Avoid: Highlight group, color key

Visual column: The column of a cell in a View, counted in terminal cells, including the width of tabs and of inline Annotations. Avoid: Display column, screen column

History

Backup: The text of a Document with unsaved changes, which dk writes to the state directory when it panics. Avoid: Swap file, recovery file

Change: One change of the version control system of a workspace, as a vcs plugin gives it, with its id: the change id of jj, or the commit id of a vcs that has no other id. Avoid: Commit, Revision

History: The Revision tree of one Document, with its current Revision and its Save markers. Avoid: Undo stack, undo list

Revision: One node in the Revision tree: the Document state after one committed Transaction. Avoid: Undo step, version

Revision tree: Every Revision of a Document, where an edit after an undo starts a new branch and no Revision is ever lost. Avoid: Undo stack

Save marker: The record that a Revision was written to disk, used to move through history by save count. Avoid: Checkpoint

Undofile: The Revision tree of a Document, stored on disk so that undo survives a restart. Avoid: Undo cache, swap file

Plugins

Capability: A permission, granted in user config, for a Plugin to reach the filesystem, processes, or the network. Avoid: Permission, scope

Default plugin: A Plugin that ships with ductus and provides a standard feature, such as the keymap, the motions, or the jj vcs plugin. It has no more trust than any other Plugin, except that the vcs plugin has a default exec grant for jj (ADR 0007). Avoid: Built-in, core plugin

Emergency mode: The state the editor enters when the keymap Default plugin fails, with a minimal native keymap that can still type, move, save, and quit. Avoid: Safe mode, fallback mode

Hook: A named editor event that a Plugin can subscribe to, such as a Document being opened or saved. Avoid: Callback, listener

Plugin: A WebAssembly component that extends the editor through the public editor API. Avoid: Extension, script, addon

Runtime directory: The directory of the files that ductus ships beside its binary, such as themes. It is <prefix>/share/ductus/runtime, or $DUCTUS_RUNTIME. It is part of the install and never part of a workspace. Avoid: Data directory, share directory

Trusted workspace: A workspace that the user has approved, so that its .ductus/ config applies like user config, and a granted Plugin can use its Capability there (ADR 0007). The workspace can have no .ductus/, as a jj repository with no ductus config. Avoid: Safe directory, allowed project

User plugin: A Plugin from plugins/*.wasm in the user config directory, other than keymap.wasm and vcs.wasm.

Language servers

Diagnostic: A message of a Language server about a Range of a Document, such as an error, with its severity. dk shows it at the end of its line and in the style of its severity, and an edit moves it with the text. Avoid: Lint, problem

Language server: A program that knows a language and talks to dk over stdio with the Language Server Protocol. A [language-server.<name>] table of languages.toml defines it, and a language names its servers. dk starts one only in a Trusted workspace. Avoid: LSP, client

LSP root: The directory that a Language server runs in and gets as its root: the topmost directory from the file up to its workspace that holds a marker of roots, or else the workspace. Avoid: Project root