feat(ui): add support for OSC 8 hyperlinks #27109

gpanders · 2024-01-20T19:14:14Z

Extmarks can contain URLs which can then be drawn in any supporting UI. In the TUI, for example, URLs are "drawn" by emitting the OSC 8 control sequence to the TTY. On terminals which support the OSC 8 sequence this will create clickable hyperlinks.

URLs are treated as inline highlights in the decoration subsystem, so they are included in the DecorHighlightInline and DecorSignHighlight structures. However, unlike other inline highlights they use allocated memory which must be freed, so they set the ext flag in DecorInline so that their lifetimes are managed along with other allocated memory like virtual text.

The decoration subsystem then adds the URLs as a new highlight attribute. The highlight subsystem maintains a set of unique URLs to avoid duplicating allocations for the same string. To attach a URL to an existing highlight attribute we call hl_add_url which finds the URL in the set (allocating and adding it if it does not exist) and sets the url highlight attribute.

This has the potential to lead to an increase in highlight attributes if a URL is used over a range that contains many different highlight attributes, because now each existing attribute must be combined with the URL. In practice, however, URLs typically span a range containing a single highlight (e.g. link text in Markdown), so this is likely just a pathological edge case.

When a new highlight attribute is defined with a URL it is copied to all attached UIs with the hl_attr_define UI event. The TUI manages its own set of URLs (just like the highlight subsystem) to minimize allocations. The TUI keeps track of which URL is "active" for the cell it is printing. If no URL is active and a cell containing a URL is printed, the opening OSC 8 sequence is emitted and that URL becomes the actively tracked URL. If the cursor is moved while in the middle of a URL span, we emit the terminating OSC sequence to prevent the hyperlink from
spanning multiple lines.

This does not support nested hyperlinks, but that is a rare (and, frankly, bizarre) use case. If a valid use case for nested hyperlinks ever presents itself we can address that issue then.

TODO:

~~Fix treesitter/highlight_spec.lua test~~
Update news.txt

gpanders · 2024-01-20T19:19:18Z

Demo:

Screen.Recording.2024-01-19.at.9.43.09.PM.mov

bfredl · 2024-01-20T20:33:30Z

src/nvim/decoration_defs.h

  DecorPriority priority;
  int hl_id;
  schar_T conceal_char;
+  String url;


As these need allocation anyway, there is no point in having them in DecorHighlightInline (as you note, these be converted to ext anyway so it is just waste of space here). better to use a code path more like line_hl_id etc to construct them.

Done in a90c842

Not sure how best to handle ephemeral extmarks with URLs now. When they are part of DecorHighlightInline they get converted in decor_sh_from_inline. I explicitly am adding a new DecorSignHighlight when sign.url.data is non null for ephemeral extmarks, which works, but maybe there is a better way.

bfredl · 2024-01-21T08:41:52Z

src/nvim/highlight.c

+/// @param url The URL to associate with the highlight attribute. An empty string indicates the
+///            end of a URL


This might be how it works in the TUI but in the highlight layer it is better to just say an empty string indicates the lack of an URL.

This is out of date now and reflects a previous implementation, thanks for catching it. Will update the comment.

bfredl · 2024-01-21T08:44:50Z

src/nvim/highlight.c

    hlattrs.cterm_ae_attr = mask;
  }

+  if (HAS_KEY_X(dict, url)) {


is this actually used anywhere? in the API layer the PR guards against this, but this breaks the memoization allocation pattern used above and for future usages it is better to leave a missing implementation to fill in, than a broken one.

It's used when called from ui_client_dict2hlattrs. Commenting this out makes the new test in tui_spec fail.

We could move these lines from dict2hlattrs into ui_client_dict2hlattrs so that it only affects the TUI.

ColinKennedy · 2024-01-21T18:44:52Z

@gpanders will this new feature be able to parse and process RFC 3986 URIs? Specifically, what I mean is that a URI may point to a website URL or to some other resource like a file on-disk, or something else. Will users be able to customize the "do it" functionality of these URIs?

Currently I'm able to use gf to "go to" a URI such as thing:/FOO(bar)/FIZZ(buzz)?version=10 by overriding 'includeexpr and 'isfname' to recognize these URI sequences. And the "do it" in this case is to open a file on disk or download a byte payload from a website. All vimscript + Python APIs. I was guessing that this PR relies on tree-sitter to do the parsing (so no 'isfname' needed in this case) but does this PR allow the user to customize what happens when a URL is found like with 'includeexpr'?

gpanders · 2024-01-21T19:34:03Z

Will users be able to customize the "do it" functionality of these URIs?

No, all this does is write a control sequence to your terminal emulator. See https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda. The terminal controls what happens when you click on the link, not Neovim.

gpanders · 2024-01-21T22:26:45Z

src/nvim/tui/tui.c

+
+    if (attrs.url.data != NULL) {
+      StringBuilder sb = KV_INITIAL_VALUE;
+      kv_printf(sb, "\x1b]8;;%s\x1b\\", attrs.url.data);


Should include an id here. attr_id maybe?

Suggested change

kv_printf(sb, "\x1b]8;;%s\x1b\\", attrs.url.data);

kv_printf(sb, "\x1b]8;id=%d;%s\x1b\\", attr_id, attrs.url.data);

This is tricky. attr_id will make the terminal highlight all URLs with the same attr_id, which we probably don't want. We don't really have a way to uniquely identify each individual hyperlink right now. We could use something like grid position where the URL starts, but don't have a way to easily get that information at the moment.

For now I'll omit the id, and we can solve this if/when it becomes a problem.

gpanders · 2024-01-21T22:28:29Z

src/nvim/tui/tui.c

+    if (tui->url.data != NULL) {
+      out(tui, S_LEN("\x1b]8;;\x1b\\"));
+    }
+
+    if (attrs.url.data != NULL) {
+      StringBuilder sb = KV_INITIAL_VALUE;
+      kv_printf(sb, "\x1b]8;;%s\x1b\\", attrs.url.data);
+      out(tui, sb.items, sb.size);
+      kv_destroy(sb);
+    }


If we are starting a new URL the old URL (if it exists) does not need to be terminated. It works just like any other SGR sequence (e.g. you don't need to "terminate" one color before starting another).

gpanders · 2024-01-22T14:13:29Z

The treesitter changes are non-trivial and will require further discussion so I'm moving those out of this PR.

test/functional/ui/decorations_spec.lua

zeertzjq · 2024-01-24T14:55:58Z

This should documented in the docs of hl_attr_define

gpanders · 2024-01-24T15:29:02Z

This should documented in the docs of hl_attr_define

d80ac48

Extmarks can contain URLs which can then be drawn in any supporting UI. In the TUI, for example, URLs are "drawn" by emitting the OSC 8 control sequence to the TTY. On terminals which support the OSC 8 sequence this will create clickable hyperlinks. URLs are treated as inline highlights in the decoration subsystem, so are included in the `DecorSignHighlight` structure. However, unlike other inline highlights they use allocated memory which must be freed, so they set the `ext` flag in `DecorInline` so that their lifetimes are managed along with other allocated memory like virtual text. The decoration subsystem then adds the URLs as a new highlight attribute. The highlight subsystem maintains a set of unique URLs to avoid duplicating allocations for the same string. To attach a URL to an existing highlight attribute we call `hl_add_url` which finds the URL in the set (allocating and adding it if it does not exist) and sets the `url` highlight attribute to the index of the URL in the set (using an index helps keep the size of the `HlAttrs` struct small). This has the potential to lead to an increase in highlight attributes if a URL is used over a range that contains many different highlight attributes, because now each existing attribute must be combined with the URL. In practice, however, URLs typically span a range containing a single highlight (e.g. link text in Markdown), so this is likely just a pathological edge case. When a new highlight attribute is defined with a URL it is copied to all attached UIs with the `hl_attr_define` UI event. The TUI manages its own set of URLs (just like the highlight subsystem) to minimize allocations. The TUI keeps track of which URL is "active" for the cell it is printing. If no URL is active and a cell containing a URL is printed, the opening OSC 8 sequence is emitted and that URL becomes the actively tracked URL. If the cursor is moved while in the middle of a URL span, we emit the terminating OSC sequence to prevent the hyperlink from spanning multiple lines. This does not support nested hyperlinks, but that is a rare (and, frankly, bizarre) use case. If a valid use case for nested hyperlinks ever presents itself we can address that issue then.

Reduces size to 32 bytes per HlAttr

luukvbaal · 2024-01-24T22:47:16Z

src/nvim/decoration.c

 void decor_redraw_sh(buf_T *buf, int row1, int row2, DecorSignHighlight sh)
 {
-  if (sh.hl_id || (sh.flags & (kSHIsSign|kSHSpellOn|kSHSpellOff))) {
+  if (sh.hl_id || (sh.url != NULL) || (sh.flags & (kSHIsSign|kSHSpellOn|kSHSpellOff))) {


Any reason not to add a kSHIsURL flag instead of checking sh.url? (Sorry for the late review was waiting if bfredl had something to say about it TBH.)

I thought about it but decided against it because it's duplicating information, so no need to waste a flag. "Non null URL" is the flag, in a sense.

I am not opposed to it though if there are other reasons to use a flag.

Other than these checks being more readable if it just used flags I don't think so. But it's so only checked a few times and sh.hl_id is checked directly as well so probably doesn't matter much :)

Extmarks can contain URLs which can then be drawn in any supporting UI. In the TUI, for example, URLs are "drawn" by emitting the OSC 8 control sequence to the TTY. On terminals which support the OSC 8 sequence this will create clickable hyperlinks. URLs are treated as inline highlights in the decoration subsystem, so are included in the `DecorSignHighlight` structure. However, unlike other inline highlights they use allocated memory which must be freed, so they set the `ext` flag in `DecorInline` so that their lifetimes are managed along with other allocated memory like virtual text. The decoration subsystem then adds the URLs as a new highlight attribute. The highlight subsystem maintains a set of unique URLs to avoid duplicating allocations for the same string. To attach a URL to an existing highlight attribute we call `hl_add_url` which finds the URL in the set (allocating and adding it if it does not exist) and sets the `url` highlight attribute to the index of the URL in the set (using an index helps keep the size of the `HlAttrs` struct small). This has the potential to lead to an increase in highlight attributes if a URL is used over a range that contains many different highlight attributes, because now each existing attribute must be combined with the URL. In practice, however, URLs typically span a range containing a single highlight (e.g. link text in Markdown), so this is likely just a pathological edge case. When a new highlight attribute is defined with a URL it is copied to all attached UIs with the `hl_attr_define` UI event. The TUI manages its own set of URLs (just like the highlight subsystem) to minimize allocations. The TUI keeps track of which URL is "active" for the cell it is printing. If no URL is active and a cell containing a URL is printed, the opening OSC 8 sequence is emitted and that URL becomes the actively tracked URL. If the cursor is moved while in the middle of a URL span, we emit the terminating OSC sequence to prevent the hyperlink from spanning multiple lines. This does not support nested hyperlinks, but that is a rare (and, frankly, bizarre) use case. If a valid use case for nested hyperlinks ever presents itself we can address that issue then.

clason · 2024-05-03T09:23:07Z

No, but you actually need to set the extmark property on the url you want to click; this is not automatic. Please ask usage questions in Chat (or in a Discussion).

github-actions bot added tui termcodes, terminfo, termcap treesitter ui labels Jan 20, 2024

github-actions bot requested review from bfredl, clason, famiu and lewis6991 January 20, 2024 19:16

gpanders force-pushed the extmark-uri-osc8 branch 2 times, most recently from 9d1678c to 4866f46 Compare January 20, 2024 19:18

gpanders force-pushed the extmark-uri-osc8 branch from 4866f46 to a9a5621 Compare January 20, 2024 19:22

bfredl reviewed Jan 20, 2024

View reviewed changes

bfredl reviewed Jan 21, 2024

View reviewed changes

gpanders commented Jan 21, 2024

View reviewed changes

gpanders force-pushed the extmark-uri-osc8 branch from 182c16d to 65aa325 Compare January 22, 2024 01:55

gpanders mentioned this pull request Jan 22, 2024

Enable hyperlinks in TUI (OSC-8) #18130

Closed

gpanders force-pushed the extmark-uri-osc8 branch from 65aa325 to ae159cd Compare January 22, 2024 14:11

gpanders force-pushed the extmark-uri-osc8 branch 2 times, most recently from c34fb9d to 5e0e935 Compare January 22, 2024 14:17

This was referenced Jan 22, 2024

feat(extmarks): subpriorities (relative to declaration order) #27131

Merged

feat(treesitter): support URLs #27132

Merged

gpanders requested a review from bfredl January 22, 2024 15:16

gpanders force-pushed the extmark-uri-osc8 branch from 5e0e935 to 6b77e8f Compare January 23, 2024 02:10

zeertzjq reviewed Jan 23, 2024

View reviewed changes

test/functional/ui/decorations_spec.lua Outdated Show resolved Hide resolved

zeertzjq removed the treesitter label Jan 23, 2024

gpanders force-pushed the extmark-uri-osc8 branch from d87d68d to 5323370 Compare January 23, 2024 18:26

clason added the ci:s390x Enable CI for s390x label Jan 23, 2024

gpanders added 11 commits January 24, 2024 15:41

Update decorations_spec test

7e2b6e5

Don't set URL in hlattrs2dict

c6e1683

use const char * instead of String

b0fbff2

Use URL indices instead of pointers in HlAttr

bb7a394

Reduces size to 32 bytes per HlAttr

use fixed size ints in HlAttrs

d65d66e

Remove TODO

6c8b9fe

Type fixes

5ad0c27

Address -Wconversion warnings

68e1514

Use DECOR_SIGN_HIGHLIGHT_INIT

5ef097f

Update hl_attr_define docs

cc7849d

gpanders force-pushed the extmark-uri-osc8 branch from d80ac48 to cc7849d Compare January 24, 2024 21:43

gpanders merged commit 6ea6b3f into neovim:master Jan 24, 2024

gpanders deleted the extmark-uri-osc8 branch January 24, 2024 22:36

github-actions bot removed request for bfredl, clason, famiu and lewis6991 January 24, 2024 22:36

luukvbaal reviewed Jan 24, 2024

View reviewed changes

pysan3 mentioned this pull request Feb 26, 2024

feat: Make concealed links print with OSC8 escape sequences nvim-neorg/tree-sitter-norg3#17

Open

This comment was marked as off-topic.

Sign in to view

neovim locked as resolved and limited conversation to collaborators May 3, 2024

		/// @param url The URL to associate with the highlight attribute. An empty string indicates the
		/// end of a URL

	kv_printf(sb, "\x1b]8;;%s\x1b\\", attrs.url.data);
	kv_printf(sb, "\x1b]8;id=%d;%s\x1b\\", attr_id, attrs.url.data);

Uh oh!

feat(ui): add support for OSC 8 hyperlinks #27109

feat(ui): add support for OSC 8 hyperlinks #27109

Uh oh!

Conversation

gpanders commented Jan 20, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gpanders commented Jan 20, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ColinKennedy commented Jan 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gpanders commented Jan 21, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gpanders commented Jan 22, 2024

Uh oh!

Uh oh!

zeertzjq commented Jan 24, 2024

Uh oh!

gpanders commented Jan 24, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as off-topic.

This comment was marked as off-topic.

This comment was marked as off-topic.

clason commented May 3, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

gpanders commented Jan 20, 2024 •

edited

Loading

ColinKennedy commented Jan 21, 2024 •

edited

Loading