Interactive Inspector

[philtweir]

What does this PR do?

Adds simple navigation to the inspector, to explore a session starting from a single command. This creates a new user flow, where a user can find a history entry in the interactive view (in, say, Global mode), and hit Ctrl+o to navigate back and forward through that command's session.

IMAGINED USE-CASE: I remembered that I did a sequence of git steps but I can't remember the order and forgot to document it. I remember that reflog was involved and want to see the actual sequence, and only those commands.

IMAGINED USE-CASE: I used a curl command to get my IP address for greenlisting before I connected to the bastion server abc.xyz over SSH - I could easily find the SSH command with abc.xyz, and go back one step in the session, but without this change, scrolling through all my curl commands ever run to find a forgotten URL/domain would be too much work.

Since this gives the inspector tab a broader purpose than viewing analytics, it needs to function even when there are not enough screen rows for charts -- hence, this PR also introduces an ultracompact mode for the inspector that just shows the neighbouring history commands (as simple scrolling three-entry list, with no panes) if there are fewer than auto_hide_height rows (default: 8). Otherwise, the inspector behaves as normal, except that Up / Down will change the focused command by navigating through the session. That means there is no "compact" mode for the inspector - when the interactive search is compact (but not ultracompact), the inspector shows its usual chart view.

The UX for this could be improved - to keep this PR as lean as it realistically can be, I have tried to keep the flow very minimal, but a follow-up PR could introduce some tooltips, nicer ultracompact formatting, etc.

A minor QoL improvement that comes with this - since I had to deal with bold text and would otherwise have need a theming exception, I took the opportunity to ensure the theme engine sets styles completely (so a theme can have bold), not just colours. To limit scope creep, I do not add TOML syntax so (for now) you can only customize colours from config files, but it means that default-bold text (etc.) can now use the theming engine if the code-defined default Meaning is bolded.

Key changes:

• introduces a simplified inspector tab, with only previous-current-next commands as rows, in compact mode
• allows navigation through session history within the inspector (so compact inspector view is still useful)

It also (see comments below):

• makes compact into compactness, an enum (to better standardize across inspector/interactive)
• makes the inspector only change layout for ultracompact mode, which is still compact+(height<8)
• clippy's complexity limit wanted draw split up a little, so not sure if this is a reasonable minimal way to do so for now
• adds a (none) theme to the theming to enable output testing without styling
• additional tests, although keen for input on how best to do these one functional test, as a starting point
• documentation minor doc changes only, as I am not sure there is much to say

Was stacked on #2357, which is now in main

Checks

• I am happy for maintainers to push small adjustments to this PR, to speed up the review cycle
• I have checked that there are no existing pull requests for the same thing

[ellie]

Generally all good, thank you! Ultra-compact works nicely.

However the inspector might need some adjusting. I run compact mode all the time (as do some others), and it will likely become the default in the future. In compact mode, the inspector looks like this regardless of size

I think it would make sense to continue to show the stats/etc if the terminal is large enough, but I do really like the scrolling through history/session.

Do you think you'd be able to split the inspector changes into a separate PR? Other than those commits, I'm happy to merge this as-is

[philtweir]

Yep, sure! Good point - thinking about your comment, I realise I haven't properly thought about that stylistically-compact vs limited-space difference, so could I suggest I do two new PRs, if that makes sense:

• inspector in ultracompact mode (so compact and <8 lines), including the interactivity (as otherwise it's a bit redundant)
• inspector in compact mode, to start the discussion about what would be useful in general to change/keep/rearrange when compact is on (as I think you & others would need to input first to make sure I go in a sensible direction)

[ellie]

That sounds good to me!

[philtweir]

I have split out #2357 as requested, which this PR is now stacked on. It has been updated to:

• make compact into compactness, an enum (to better standardize across inspector/interactive)
• made the inspector only change on ultracompact mode, which is still compact+(height<8)
• clippy's complexity limit wanted draw split up a little, so not sure if this is a reasonable minimal way to do so for now

The intention (as above) would be to open a comment/forum-post to work out behaviour for a new PR for the inspector in (non-ultra-) compact mode, but this PR no longer has any change to the inspector except in ultracompact mode.

[philtweir]

Updated with a test - this turned out to be the hardest bit of the whole process, as the only sensible way I could see of testing a layout switch like this was to compare the output with TestBackend::assert_buffer_lines, but I could not for the life of me get it to match, likely due to ANSI code placement and how buffer area is calculated in different places in Crossterm/Ratatui :/

However, this forced me to take the PR beyond the inspector to enable a more sensible approach, by tweaking the new theming module -- this makes it possible to do the comparison without any styling. Obviously, this means the ultracompact-inspector styling is not checked, but the rest of the test is essential a functional test of ultracompact inspector layout, which is what I really wanted, rather than a brittle integration test tied to the default theme behaviour.

The downside is that I needed to add a new in-built theme called (none) (parentheses to highlight it is special, not general purpose). This only ever returns ContentStyle::default() so nothing is ever styled up, regardless of the Meaning passed. This might be separately useful where ANSI codes are not desirable or a theme author wishes to avoid inheriting anything from default now or in future, they could name (none) explicitly as a parent theme.

There is not much to put in the docs, but I have updated that PR too, so marking this ready-for-test.

[philtweir]

As a side-note, to make boldness a property the theming can control, it also adds StyleFactory::from_fg_color_with_attributes so that in-built themes can pass Crossterm Attributes as well as a foreground colour. Given agreement on syntax, this could be exposed to the theming YAML (as could background properties). Would be keen to know if that is desirable first before proposing changes.

[atuin-bot]

This pull request has been mentioned on Atuin Community. There might be relevant details there:

https://forum.atuin.sh/t/feedback-playing-with-inspector/218/6

[philtweir]

Rebased, as #2657 came up again. Wondering if this could be further split to make it more mergeable, or is it OK as-is?

As a side-note, I could see the inspector compact view going a different direction in future, so not hugely wedded to this implementation, but it seems like a reasonable stepping stone, at least?

[philtweir]

Actually, one way to split this up would be to add the interactivity for the inspector in one PR, and then the ultracompact inspector in a second 🤔

[philtweir]

Just to confirm, the navigation works in both ultracompact and normal modes.

There is no special "compact" mode so it is always ultracompact (if below auto_hide_height) or normal, so in the case where the inspector has too few lines to show anything usefully, but not so low as your auto_hide_height , you just get a not very useful inspector window. But that is the case currently, anyway.

Screencast.From.2025-09-21.13-36-15.mp4

[philtweir]

(Rebased on main)

[ellie]

ok! super happy with this, thank you! really appreciate your work and patience here <3

[ltrzesniewski]

A little comment:

I had to quickly review this, and I think there's currently no way to reach InputAction::AcceptInspecting with accept being true. No big deal though I suppose.

[philtweir]

Thanks @ltrzesniewski - I will take another look, it might be something I missed while rebasing!