orgmode feat(cookie): implement virtual cookies

Summary

This PR adds virtual cookies, a way of using extmarks to get live updating cookies for progress.

Currently it is only implemented for headlines, does not support list items.

This slightly modifies the headlines class to expose progress amounts from the headlines.

The virtual cookies prioritize list checkboxes over todo checkboxes for determining progress. Would it be preferred to flip that OR combine the totals from both as our progress?

Virtual cookies are gated behind ui.cookies_use_extmarks and are disabled by default.

I have not added tests for them, I consider them largely experimental (though pretty robust from my experience) and didn't allocate the time to write tests for them.

See more details from my earlier comment (https://github.com/nvim-orgmode/orgmode/issues/745#issuecomment-2902634050) for additional information.

Related Issues

Closes #745

Changes

Added virtual cookie implementation
Exposed progress counts for cookies in the Headline class
Updated docs to include new feature in configuration.org
Added Org cookie_mode command for toggling cookies on & off in the current buffer

Checklist

I confirm that I have:

[x] Followed the Conventional Commits specification (e.g., feat: add new feature, fix: correct bug, docs: update documentation).
[x] My PR title also follows the conventional commits specification.
[x] Updated relevant documentation, if necessary.
[x] Thoroughly tested my changes.
[x] Added tests (if applicable) and verified existing tests pass with make test. (Ensured existing tests still pass)
[x] Checked for breaking changes and documented them, if any.

Jun 02 '25 00:06 PriceHiller

And also expected to use a default "eol" virtual text that will show on the right of text, like diagnostics do.

I avoided that purely because it can be difficult to see a cookie when we have a bunch of tags on a given headline.

I understand it would look strange if we would have both "regular text cookie" and "virtual text cookie" one beside another, but concealing the current cookie looks a bit odd. A slight improvement would be to not conceal the text and use overlay virtual text.

Without the conceal it can be difficult to actually delete the underlying cookie as it's unclear what is actually being selected/modified if the cookie is overlayed and a user wants to edit the underlying cookie text. In my mind we only want to show the virtual cookie and suppress the "real" cookie when possible as the virtual cookie gets live updates and will be in sync with the actual state of the headlines.

I'm not really a user of the cookies, so I'd like to understand your usage of it. Do you need to have the actual cookie text for later use (exporting or something else), or it's only visual? Are there situations where you want cookies somewhere but not on other places?

It's purely visual for me for quickly tracking progress on a larger TODO item. I figured that if a user wants to see progress then they'd add a cookie to track progress. I'm totally open to putting virtual cookies on all headlines regardless of if an underlying cookie has been created.

Again, an issue that can crop up is if we overlay the cookie with a virtual cookie, it can be difficult to modify the underlying cookie text. That was why I have this setup as it currently is.

Here's what I'll do:

Make virtual cookies appear on all headlines when applicable (when there's TODO or checkbox subitems basically)
I'll combine the progress on both the TODO items and the checkboxes beneath the current headline into the cookie.

Here's what I need answered before I can continue on some of this:

Let me know if you still desire an EOL or Inline cookie (considering that tags can cause a cookie to go off screen)
How do you want me to handle the scenario when we have a "physical/real" cookie and a virtual cookie on the same headline?

Jun 02 '25 21:06 PriceHiller

Latest push covers

Make virtual cookies appear on all headlines when applicable (when there's TODO or checkbox subitems basically)
I'll combine the progress on both the TODO items and the checkboxes beneath the current headline into the cookie.

As well as

Allowing users to specify the default "cookie type", whether or not to show a / or a % for the sign in the cookie if there isn't a "real" cookie specified for the given headline.
Support for toggling the type of default virtual cookie for headlines that do not specify the "real" cookie (via Org cookie_type)
Removed the [???] "unknown" cookie type, no longer applicable seeing as we're now drawing cookies for all headlines that have subitems
Small improvement to deleting extmarks
Support placing the virtual cookie at the end of a headline title (before the tags if they exist) when there's no "real" cookie in the headline

Jun 02 '25 22:06 PriceHiller

Updated documentation to reflect the new changes.

Jun 02 '25 22:06 PriceHiller

I've realized this has sat open since the start of summer. Sorry about that, got tied in a job and other things. I'm likely not going to finish this out in the near future so instead of keeping this PR open, I'll close this out.

I agree with a lot of comments made by @celsobenedetti -- I just never spared the time to respond to them and actually update this branch to resolve them and ultimately forgot for a long while. If anyone wants to grab this can carry it onwards, feel free to do so.

:slightly_smiling_face:

Nov 01 '25 17:11 PriceHiller