Skip to content

feat: less pager mode with smooth Kitty image scrolling and Mermaid theming - #67

Open
kkovary wants to merge 6 commits into
atani:mainfrom
kkovary:pr/less-mode-and-mermaid-theme
Open

feat: less pager mode with smooth Kitty image scrolling and Mermaid theming#67
kkovary wants to merge 6 commits into
atani:mainfrom
kkovary:pr/less-mode-and-mermaid-theme

Conversation

@kkovary

@kkovary kkovary commented Jun 19, 2026

Copy link
Copy Markdown

Summary

Adds a less-style pager, Mermaid theming, and a live-reload watch mode, and makes line-by-line scrolling + terminal-aware theming the defaults.

Pager: new less mode (now the default)

  • Scrolls a line at a time (j/k, arrow keys, mouse wheel) instead of more's page jumps, plus half-page (d/u), page (space/b), g/G top/bottom, and / ? n N search.
  • On Kitty-graphics terminals (Kitty, Ghostty), inline Mermaid diagrams scroll smoothly: scroll position is tracked in display rows and each frame emits a vertically-cropped Kitty placement for the visible slice of an image, so diagrams scroll partially off-screen like text instead of popping in/out. iTerm2/sixel keep the existing atomic behavior.
  • Redraws use synchronized output (DEC mode 2026), with input coalescing and no-op-repaint skipping, to eliminate flicker on fast key-repeat and mouse scrolling.

Mermaid: mermaid.theme config (default auto)

  • Applies a Mermaid theme to inline images and --pdf export: auto, light/default, dark, forest, neutral, base.
  • auto queries the terminal background via OSC 11 and renders dark diagrams on a dark background, light otherwise. Falls back to light when the background can't be determined (e.g. PDF export to a file).

Watch mode (--watch)

  • Watches the input file and refreshes the pager in place when it changes, preserving scroll position — for an edit-in-one-pane / preview-in-another workflow.
  • Polls mtime+size with a debounce (coalescing rapid saves). The pager loop becomes event-driven: a goroutine feeds terminal bytes to a channel and the loop selects over keystrokes + a reload signal, so the view refreshes without a keypress. Diagrams re-render on change.
  • --watch / --no-watch flags and a pager.watch config option, off by default. Gated to a file argument rendered to a TTY; otherwise renders once with a note.

Defaults & docs

  • Default pager.mode is now less (was more); default mermaid.theme is auto.
  • README documents pager.mode, pager.watch, and mermaid.theme.

Behavior change

The default pager changes from more to less. Users who prefer the old behavior can set {"pager": {"mode": "more"}}. vim mode is unchanged.

Testing

  • New unit tests: Kitty crop pixel math, row-scroll/segment math and search, OSC 11 color parsing + luminance threshold, theme resolution, watcher change-detection + debounce, reload scroll preservation, and config defaults.
  • go build ./..., go vet ./..., and the full go test ./... suite (including the Chrome-backed Mermaid tests) pass, plus -race on the watch/pager packages.

Notes

  • Smooth image scrolling and watch require the Kitty graphics protocol for inline diagrams; other terminals fall back gracefully.
  • The first inline-diagram render adds a one-time ~200ms terminal background query (only when a document contains diagrams).
  • Watch detects the terminal background via stdin and is gated to a file argument, so cat foo.md | glowm --watch does not watch.

kkovary added 6 commits June 19, 2026 12:28
…id theme config

Pager:
- Add a 'less' pager mode that scrolls by line (j/k, arrows), half-page
  (d/u), page (space/b), g/G, and / ? n N search, instead of more's page
  jumps.
- On Kitty-graphics terminals (Kitty, Ghostty), less mode scrolls images
  smoothly: scroll position is tracked in display rows and each redraw emits
  a vertically-cropped Kitty placement (EncodeKittyCrop) for the visible
  slice, so diagrams scroll partially off-screen instead of popping in/out.
  iTerm2/sixel keep the atomic fallback.

Mermaid:
- Add config 'mermaid.theme' (light/default, dark, forest, neutral, base);
  drives the Mermaid theme and page background for inline images and PDF.
  Unknown values warn and fall back to default.

Includes unit tests for crop pixel math, row-scroll/segment math, search,
and theme resolution.
Wrap each redraw in synchronized output (DEC mode 2026) so the terminal
presents the clear-then-repaint as one atomic frame, coalesce already-
buffered input (fast key-repeat / mouse wheel) into a single repaint, and
skip repaints when the visible frame would not change.
…al background

- Make 'less' the default pager mode so new installs get line-by-line
  scrolling (with smooth inline images on Kitty/Ghostty) out of the box.
- Add an 'auto' Mermaid theme (now the default) that queries the terminal
  background via OSC 11 and renders dark diagrams on a dark background, light
  otherwise. Falls back to light when the background can't be detected (e.g.
  PDF export to a file).
- Document pager.mode and mermaid.theme options in the README.
Watch the input file and refresh the pager in place when it changes, for an
edit-in-one-pane / preview-in-another workflow.

- internal/watch: mtime+size polling with debounce, coalescing rapid saves.
- Event-driven less pagers (text and smooth-Kitty): a goroutine pumps terminal
  bytes into a channel and the loop selects over keystrokes + a reload signal,
  so the view refreshes without a keypress while preserving scroll position.
  Non-watch pager paths are unchanged.
- --watch / --no-watch flags and a pager.watch config option, off by default.
  Gated to a file argument rendered to a TTY; otherwise renders once with a note.
- Resolve the 'auto' text style once before raw mode so reloads keep the initial
  theme instead of re-querying the terminal mid-pager.
- Docs and unit tests (watcher change-detection/debounce, applyContent scroll
  preservation, segment rebuild, chanReader).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant