Skip to content
KN-86 Deckline

history.el

What it is

Section titled “What it is”

history.el is a small Emacs Lisp package that provides a non-destructive navigation history for code editors — a richer alternative to Emacs’s built-in pop-global-mark. The key design choice: where pop-global-mark removes the most-recent mark from the stack as you traverse it (so you can’t easily walk the whole history), history.el preserves every mark and indexes into the history. You can walk forward and backward through your navigation trail without losing any of it. The package smartly skips entries pointing into killed buffers or dead symbol references.

The data model is illustrated in the README as a doubly-linked list with a sliding index pointer:

  (1) - (2) - (3) - (4) - (5)
                           ^ index

history-prev-history moves the index left; history-next-history moves it right; history-add-history inserts a new node at the current index (the entries to the right of the index are kept, not truncated).

For KN-86 this is the right reference for the REPL surface’s navigation history (ADR-0016 nEmacs) — and more broadly, for any “go back / go forward” navigation across the deck’s surfaces.

Key takeaways for KN-86

Section titled “Key takeaways for KN-86”
  • Non-destructive history as a runtime doctrine. When the operator navigates from one cart surface to another, or from one REPL form to another, or from one mission contract to its detail and back, the navigation should not destroy where they were before. history.el’s doubly-linked-list-with-index model is the right reference implementation. KN-86 should commit to this at the runtime level: every navigation push creates a new node, the user can walk in either direction, nothing is lost.
  • Index pointer, not stack pointer. The distinction matters. A stack would pop entries on traversal; the index leaves them in place. KN-86 navigation history should follow history.el: the user can BACK 5 times, then FORWARD 5 times, and end up exactly where they started, with the same intermediate views available.
  • “Smartly ignore killed buffers.” The model is “skip stale entries.” For KN-86 the analog is navigation entries that point to state that’s been swapped out — e.g., a mission that no longer exists because its phase resolved, a cart surface whose cart was ejected. The runtime should skip these on traversal rather than blocking the user at a broken node.
  • Compose with Xiki’s expansion tree. Xiki’s interaction model is a tree of expansions; history.el’s is a linear list of navigations. The two compose: the user expands (Xiki) or navigates (history.el) and the runtime tracks both. The expansion creates a tree-shaped artifact in the buffer; the navigation creates a linear traversal across artifacts.
  • No prior art conflict with l123 or webmacs. l123 has its own undo (Alt-F4) and Range Search (Find/Replace). webmacs has browser-style back/forward. history.el is the cleaner, more general model and is what KN-86 should base its runtime navigation on.

Image

Section titled “Image”

No image downloaded.

Notes

Section titled “Notes”
  • Direct citation for ADR-0016 nEmacs — history.el is the structural reference for the REPL navigation history. Adopt the doubly-linked-list-with-index model.
  • Promote item: Non-destructive navigation history as a v0.1 runtime affordance. Adds to the promote-to-spec list. Compose with the universal verb set (exwm.md takeaway): BACK and FORWARD should be deck-wide TERM-line verbs.
  • Cross-link xiki.md for the expansion-tree companion.
  • Cross-link worldmonitor.md / emacs-request.md for the data-fetch pattern that the navigation history is layered over.