[PR #19143] Rewrite media resource handling (relative path icons, web URLs) #31724

Open
opened 2026-01-31 09:49:09 +00:00 by claunia · 0 comments
Owner

Original Pull Request: https://github.com/microsoft/terminal/pull/19143

State: closed
Merged: Yes


This pull request broadly rewrites how we handle all media resources in
the Terminal settings model.

What is a media resource?

A media resource is any JSON property that refers to a file on disk,
including:

  • icon on profile
  • backgroundImage on profile (appearance)
  • pixelShaderPath and pixelShaderImagePath on profile (appearance)
  • icon on command and the new tab menu entries

The last two bullet points were newly discovered during the course of
this work.

Description of Changes

In every place the settings model used to store a string for a media
path, it now stores an IMediaResource.

A media resource must be resolved before it's used. When resolved, it
can report whether it is Ok (found, valid) and what the final
normalized path was.

This allows the settings model to apply some new behaviors.

One of those new behaviors is resolving media paths relative to the
JSON file that referred to them.
This means fragments and user settings
can now contain local images, pixel shaders and more and refer to them
by filename.

Relative path support requires us to track the path from which every
media resource "container" was read1 . For "big" objects like Profile,
we track it directly in the object and for each layer. This means that
fragments updating a profile pass their relative base path into the
mix. For some of the entries such as those in newTabMenu, we just wing
it (#19191). For everything that is recursively owned by a parent that
has a path (say each Command inside an ActionMap), we pass it in from
the parent during media resolution.

During resolution, we now track exactly which layer an icon,
background image, or pixel shader path came from and read the "base
path" from only that layer. The base path is not inherited.

Another new behavior is in the handling of web and other URLs.

Canonical and a few other WSL distributors had to resort to web URLs for
icons because we did not support loading them from the package. Julia
tried to use ms-appx://JuliaPackageNameHere/path/to/icon for the same
reason. Neither was intended, and of the two the second should have
worked but never could2 .

For both http(s?) URLs and ms-appx:// URLs which specify a package
name, we now strip everything except the filename. As an example...

If my fragment specifies https://example.net/assets/foo.ico, and my
fragment was loaded from C:\Fragments, Terminal will look only at
C:\Fragments\foo.ico.

This works today for Julia (they put their icon in the fragment folder
hoping that one day we would support this.) It will require some work
from existing WSL distributors.

I'm told that this is similar to how XML schema documents work.

Now, icons are special. They support Emoji and Segoe Icons. This PR
adds an early pass to avoid resolving anything that looks like an
emoji.

This PR intentionally expands the heuristic definition of an emoji. It
used to only cover 1-2 code unit emoji, which prevented the use of any
empji more complicated than "man in business suite levitating."

An icon path will now be considered an emoji or symbol icon if it is
composed of a single grapheme cluster (as measured by ICU.)

This is not perfect, as it errs on the side of allowing too many
things... but each of those things is technically a single grapheme
cluster and is a perfectly legal FontIcon ;)

Profile icons are even more special than icons. They have an
additional fallback behavior which we had to preserve. When a profile
icon fails validation, or is expressly set to null, we fall back to
the EXE specified in the command line.

Because we do this fallback during resolution, and the icon may be
inherited by any higher profile,
we can only resolve it against the
commandline at the same level as the failed or nulled icon.

Therefore, if you specify icon: null in your defaults profile, it
will only ever resolve to cmd.exe for any profile that inherits it
(unless you change defaults.commandline).

This change expands support for the magic keywords desktopWallpaper
and none to all media paths (yes, even pixelShaderPath... but also,
pixelShaderImagePath!) It also expands support for environment
variables
to all of those places. Yes, we had like forty different
handlers for different types of string path. They are now uniform.

Resource Validation

Media resources which are not found are "rejected". If a rejected
resource lives in user settings, we will generate a warning and
display it.

In the future, we could detect this in the Settings UI and display a
warning inline.

Surprises

I learned that Windows.Foundation.Uri parses file paths into file://
URIs, but does not offer you a way to get the original file path back
out. If you pass C:\hello world, Uri.Path will return
/C:/hello%20world. I kid you not.

As a workaround, we bail out of URL handling if the : is too close to
the start (indicating an absolute file path).

Testing

I added a narow test hook in the media resource resolver, which is
removed completely by link-time code generation. It is a real joy.

The test cases are all new and hopefully comprehensive.

TODO

  • Write docs explaining the HTTP thing

Closes #19075
Closes #16295
Closes #10359 (except it doesn't support fonts)
Supersedes #16949 somewhat (WT_SETTINGS_DIR)
Refs #18679

Refs #19215 (future work)
Refs #19201 (future work)
Refs #19191 (future work)


  1. We don't bother tracking where the defaults came from, because we
    control everything about them. ↩︎

  2. Handling a ms-appx path requires us to add their package to our
    dependency graph
    for the entire duration during which the resource will
    be used. For us, that could be any time (like opening the command
    palette for the first time!) ↩︎

**Original Pull Request:** https://github.com/microsoft/terminal/pull/19143 **State:** closed **Merged:** Yes --- This pull request broadly rewrites how we handle all media resources in the Terminal settings model. ## What is a media resource? A media resource is any JSON property that refers to a file on disk, including: - `icon` on profile - `backgroundImage` on profile (appearance) - `pixelShaderPath` and `pixelShaderImagePath` on profile (appearance) - `icon` on command and the new tab menu entries The last two bullet points were newly discovered during the course of this work. ## Description of Changes In every place the settings model used to store a string for a media path, it now stores an `IMediaResource`. A media resource must be _resolved_ before it's used. When resolved, it can report whether it is `Ok` (found, valid) and what the final normalized path was. This allows the settings model to apply some new behaviors. One of those new behaviors is resolving media paths _relative to the JSON file that referred to them._ This means fragments and user settings can now contain _local_ images, pixel shaders and more and refer to them by filename. Relative path support requires us to track the path from which every media resource "container" was read[^2]. For "big" objects like Profile, we track it directly in the object and for each layer. This means that fragments **updating** a profile pass their relative base path into the mix. For some of the entries such as those in `newTabMenu`, we just wing it (#19191). For everything that is recursively owned by a parent that has a path (say each Command inside an ActionMap), we pass it in from the parent during media resolution. During resolution, we now track _exactly which layer_ an icon, background image, or pixel shader path came from and read the "base path" from only that layer. The base path is not inherited. Another new behavior is in the handling of web and other URLs. Canonical and a few other WSL distributors had to resort to web URLs for icons because we did not support loading them from the package. Julia tried to use `ms-appx://JuliaPackageNameHere/path/to/icon` for the same reason. Neither was intended, and of the two the second _should_ have worked but never could[^1]. For both `http(s?)` URLs and `ms-appx://` URLs which specify a package name, we now strip everything except the filename. As an example... If my fragment specifies `https://example.net/assets/foo.ico`, and my fragment was loaded from `C:\Fragments`, Terminal will look *only* at `C:\Fragments\foo.ico`. This works today for Julia (they put their icon in the fragment folder hoping that one day we would support this.) It will require some work from existing WSL distributors. I'm told that this is similar to how XML schema documents work. Now, icons are special. They support _Emoji_ and _Segoe Icons_. This PR adds an early pass to avoid resolving anything that looks like an emoji. This PR intentionally expands the heuristic definition of an emoji. It used to only cover 1-2 code unit emoji, which prevented the use of any empji more complicated than "man in business suite levitating." An icon path will now be considered an emoji or symbol icon if it is composed of a single grapheme cluster (as measured by ICU.) This is not perfect, as it errs on the side of allowing too many things... but each of those things is technically a single grapheme cluster and is a perfectly legal FontIcon ;) Profile icons are _even more special_ than icons. They have an additional fallback behavior which we had to preserve. When a profile icon fails validation, or is expressly set to `null`, we fall back to the EXE specified in the command line. Because we do this fallback during resolution, _and the icon may be inherited by any higher profile,_ we can only resolve it against the commandline at the same level as the failed or nulled icon. Therefore, if you specify `icon: null` in your `defaults` profile, it will only ever resolve to `cmd.exe` for any profile that inherits it (unless you change `defaults.commandline`). This change expands support for the magic keywords `desktopWallpaper` and `none` to all media paths (yes, even `pixelShaderPath`... but also, `pixelShaderImagePath`!) It also expands support for _environment variables_ to all of those places. Yes, we had like forty different handlers for different types of string path. They are now uniform. ## Resource Validation Media resources which are not found are "rejected". If a rejected resource lives in _user_ settings, we will generate a warning and display it. In the future, we could detect this in the Settings UI and display a warning inline. ## Surprises I learned that `Windows.Foundation.Uri` parses file paths into `file://` URIs, but does not offer you a way to get the original file path back out. If you pass `C:\hello world`, _`Uri.Path`_ will return `/C:/hello%20world`. I kid you not. As a workaround, we bail out of URL handling if the `:` is too close to the start (indicating an absolute file path). ## Testing I added a narow test hook in the media resource resolver, which is removed completely by link-time code generation. It is a real joy. The test cases are all new and hopefully comprehensive. ## TODO - [ ] Write docs explaining the HTTP thing Closes #19075 Closes #16295 Closes #10359 (except it doesn't support fonts) Supersedes #16949 somewhat (`WT_SETTINGS_DIR`) Refs #18679 Refs #19215 (future work) Refs #19201 (future work) Refs #19191 (future work) [^1]: Handling a `ms-appx` path requires us to _add their package to our dependency graph_ for the entire duration during which the resource will be used. For us, that could be any time (like opening the command palette for the first time!) [^2]: We don't bother tracking where the defaults came from, because we control everything about them.
claunia added the pull-request label 2026-01-31 09:49:09 +00:00
Sign in to join this conversation.
No Label pull-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/terminal#31724