Custom icons for extensions and commands

[BennoCrafter]

Following up on the Discord chat about custom icons. I took a look at how asyar is currently handling icons and it's mostly implemented.

Proposal

• When extensions are discovered, turn relative manifest.icon and commands[].icon into asyar-extension://{id}/{path}. Reject .. and absolute paths, and fall back to the default icon. Remove the duplicated resolution in extensionStateManager. Emoji and icon: keep working, so existing extensions don't deprecaete.

• Apply the same normalization to commands registered at runtime, ActionType.icon and NotificationType.icon.

• Replace the repeated emoji/icon:/image branching in LauncherListRow, ActionListPopup, SearchHeader, InformationPanel and ExtensionDetailPanel with one component.

• monochrome icons can be recolored with CSS mask-image filled with currentColor. Detect them with e.g. *-template.svg or a tint flag later.

• extension SVGs only go through <img> or a CSS mask, never {@html}, so scripts inside an SVG never run.

• files live in public/assets/. Vite copies them into dist/, and the existing zip step packages them.

• Take the extension icon out of the package during publish, or upload it separately, so the store page can show it.

• The CSP allows https://**, so an extension icon can be a remote URL. Every launcher search would then contact a third-party server, which leaks the user's IP address. I'd suggest allowing only bundled files, data: and icon: for extension icons.

I'm happy to start there if this direction sounds good.

[Xoshbin]

Hey @BennoCrafter

thanks for opening this. I wanted to do my own research first. I held off on this feature for a long time because I wanted it to look good and stay fast. I agree with your direction. Below is what I found, and where I'd go a bit further so we fix the base once instead of patching each spot.

Some of this is already broken today

The problem is bigger than "emoji only":

• Command icons in root search use the raw manifest value. A relative path like assets/foo.png shows up as text in the icon box. Only Settings resolves extension icons (extensionStateManager). That's the duplicated logic you mentioned.
• The shell consent dialog and the shell trust list build their own asyar-icon://{id}/{icon} URLs. That scheme only serves the app-icon cache and rejects any /. So these icons are always broken.
• The docs say relative paths work everywhere. They don't.
• asyar-extension:// sends no Cache-Control header. Files from extension views can end up in the same WebKit cache that grew to 55 GB for you. The real cause: each scheme handler sets its own headers, and the one that forgets leaks.

All of these have one root cause: there's no single place that turns an icon into something we can show. Every component and every scheme does its own thing. So I want to build that one place properly.

The core: one typed icon, resolved in Rust

• One resolver, in Rust, at discovery. Discovery and the search index already live in Rust. So discovery.rs gets one function that turns any icon into a typed ResolvedIcon (glyph, emoji, image or remote). We export the type through the generated bindings.ts, so the frontend never guesses the kind from the start of a string again.
• Delete, don't fix. isIconImage, isBuiltInIcon and the hand-built URLs get deleted. The same resolver also handles runtime commands, actions and notifications.
• One component that renders a ResolvedIcon. It replaces the repeated code in LauncherListRow, ActionListPopup, SearchHeader, InformationPanel and ExtensionDetailPanel.
• Path safety in the resolver: reject .. and absolute paths, and fall back to the default icon, like you proposed.
• No {@html} for extension SVGs. Agreed 100%. Only <img> or a CSS mask.

One icon field, two forms

I don't want to add new icon fields over time. Instead, the existing icon accepts two forms, a bit like Raycast's Image:

• The short string we have today. It stays valid forever and is not deprecated: "icon:timer", "assets/icon.png", emoji.
• An object for richer cases:

"icon": { "source": "assets/icon.png", "dark": "assets/icon@dark.png", "tint": true }

Rust reads both into the same ResolvedIcon, so the rest of the app only sees one shape. Your mask-image + currentColor idea fits here as tint: true, instead of a -template.svg filename rule.

Older launchers need nothing new. The manifest already has asyarSdk and minAppVersion. Discovery and the Store check them and refuse extensions that need a newer Asyar. So an extension that uses the object form just declares the SDK version that adds it.

The design side, the main reason hold me back for a long time

I looked at how Raycast keeps its Store looking consistent. It comes down to two kinds of icons:

1. Identity icons (the extension and its commands in root search). Full colour, like small app icons, and they must work in light and dark. The Raycast Store rejects extensions that keep the default icon, and Raycast gives authors a Figma template and an icon maker.
2. Glyph icons (list items and actions inside a command). Always one colour, from the built-in set, and they follow the theme.

Asyar has both kinds, but mixes them. Built-ins use the white glyph on the blue tile from #301. Almost every extension uses an emoji. Emoji look different on macOS, Windows and Linux, and they clash with the tiles next to them. Two ideas from this:

• Glyph + colour tiles. Most authors aren't designers, so they use emoji. With the object form, an extension can write { "glyph": "timer", "color": "orange" } and the host draws it on a tile, like built-ins but in the author's colour. The colour comes from a fixed palette linked to theme tokens, so it works in light and dark. Every extension then matches the built-ins on every OS. It's also the fastest option: inline SVG, no file, no image decoding.
• Action panel alignment. Raycast tells authors to give either all actions an icon or none. We can do it in the host instead: if any action in a section has an icon, the others get an empty space so the text lines up.

Performance and disk

• Small icons at install, in the extension's own folder. A 512px PNG shown at 24px still takes about 1 MB of memory once decoded. At install, Rust writes a 64px copy (about 16 KB) into the extension's install folder. SVG files stay as they are, since they're already small and sharp at any size. Uninstall or update removes the copies automatically, so there's no extra cache folder to manage.
• One response builder for every custom scheme. asyar-extension, asyar-icon, asyar-thumb, and any future scheme all go through one builder that always sets the cache policy. One test checks every scheme. After the 55 GB you hit, I want this impossible to forget, not just fixed for one more scheme.
• No layout jumps. Every icon gets a fixed width and height plus decoding="async", so rows don't jump while you type.

Remote icons

I looked at this more closely, and it's bigger than the IP leak. Extensions can't reach the internet by themselves. Their sandbox CSP blocks it, and every request goes through the Rust network path, which checks the network permission. Icons are the only exception: the launcher window allows img-src https://*. So an extension without network permission can still send data out by returning an icon URL like https://example.com/x.png?data=….

So remote icons should go through the same path as every other request from that extension:

• Manifest and command icons: bundled files, data:, icon: or the object form only. We know them at install time, so they don't need to be remote.
• Icons in search results and actions: https:// keeps working for extensions with the network permission. Asyar fetches the icon through the same fetch_scoped path that extension requests already use, so it gets the same permission, private-network and LAN checks.
• What that path sends: no cookies, no referrer, and a generic user-agent. It only needs a bytes version of the response, because today it returns text.
• Size and speed: the icon is shrunk to 64px like bundled ones. The row shows the fallback icon until the real one is ready, so typing never waits on the network.
• Extensions without network get the fallback icon and a dev warning.
• Then we remove https://* from the launcher's CSP. After that, every extension request goes through one checked path, with no exceptions.

Extensions that already have network permission won't notice anything. Extensions without it lose icons that should never have loaded.

The Store

The Store has never shown real icons; every extension gets the initials gradient. I'll handle the website side myself, so the Store shows the same icon you see after installing. The only part that touches the CLI: check at build time that the icon file really exists in dist/, and include the icon file in theme packages.

Suggested order

1. The Rust resolver + ResolvedIcon + one icon component. This deletes the old string checks and hand-built URLs, which fixes the broken spots too. It's the big one, and you're welcome to start here.
2. One response builder for all custom schemes, plus 64px copies at install in the extension folder.
3. The object form of icon (dark, tint, glyph + colour tiles), using the existing asyarSdk check for older launchers, plus action panel alignment.
4. Remote icons through fetch_scoped (with a bytes version and a size limit), then removing https://* from the CSP.
5. Store icons (I'll do the website side in parallel), plus the two small CLI checks.

Sorry for the very long reply 😅 I took my time on purpose. As I said on Discord, I think this is very possible, but it touches a lot of the core: Rust discovery, the search index, the URI schemes, the network layer, the CSP, the SDK manifest, and even the website. So I wanted to think it through properly before we start, and do it right once instead of patching it later.

None of this is final. I'd really like to hear what you think. If you have a better idea for any part, technical or design, please tell me. You already looked into the code and found most of this yourself, so your view matters a lot here. And if some parts feel too big, we can talk about how to split them up.

[BennoCrafter]

@Xoshbin

Removing https://* from the CSP breaks launchers images too. The store loads iconUrl and screenshots from the web (store/DetailView.svelte), and the account tab loads the OAuth avatar (AccountTab.svelte). So instead of removing https://* completly an allow list would be imo the better approach.

64px are enough for a 24px row at the launcher, but the settings detail panel render larger.

The object forpm should be a tagged union. {source, dark, tint} and {glyph, color} exclude each other, so the schema needs to say so. The CLI should detect them and reject mixed forms.

But mostly I agree with all of your points :)

[Xoshbin]

Hey @BennoCrafter,

thanks, I went through each point in the code.

CSP. You're right, removing https://* would break the launcher's own images. While checking, I also found more views that show images from any host. So I'd sort the launcher's images into three groups:

• Store images: this part is done in feat(cli): ship README and icon in the package for the Store #956, following the way VS Code does it, and it's basically your first idea of taking the icon out of the package at publish:
  • asyar publish turns relative README links like docs/screenshot.png into full GitHub links pinned to the release tag, and puts the README inside the zip. That fixes the broken README images on asyar.org and in the launcher Store.
  • It checks that the icon file is really in the package. The website takes the icon out of the zip and serves it, so the Store finally shows real icons instead of initials. Like VS Code, the Store never serves SVG (it only warns, because SVG is still fine as a launcher icon).
  • It also stops when there are uncommitted or unpushed changes and tags the exact commit, so the zip, the README links and the Store page always match.
• Extension icons: the resolver handles them. https:// icons go through fetch_scoped and come back as a local image, never straight into an <img>.
• User content (AI chat replies through renderMarkdown, and the clipboard HTML preview): these can contain images from any host. That's its own issue, and I'll open one.

Because README images and user content can come from any host, I won't remove https://* from img-src in this work. The leak you found is closed by the resolver, since extension icons never reach an <img> directly. Tightening img-src can come later, in that separate issue.

Icon size. Good catch, and it goes further than the Settings panel. Asyar also runs on Windows and Linux, where high-DPI screens often use 150–300% scaling. At 300%, a 22px launcher row needs 66px and the 28px Settings icon needs 84px, so 64px is too small there. I'll store a 128px copy instead. That covers every surface we have today at up to 300%, and it's still only about 64 KB in memory once decoded, compared to about 1 MB for a 512px original. It's made once at install, and the same file is used everywhere. SVGs stay as they are.

Tagged union. Agreed. The manifest checks live in the CLI (asyar-sdk/cli/lib/manifest.ts) and in the Rust manifest parser. Both will accept exactly one of the two object forms:

• { "source", "dark"?, "tint"? } is the image form.
• { "glyph", "color" } is the glyph + colour tile form.

Mixing them (for example glyph together with source) is an error with a clear message, not something we guess at. The plain string form stays as it is.

Updated order

1. The Rust resolver + ResolvedIcon + one icon component, shaped around the tagged union from the start. Done in Resolve icons once in Rust and render them with one component (#949 step 1) #964
2. One response builder for all custom schemes, plus 128px copies at install in the extension folder. Done in Feat/scheme-response-builder #988
3. The object form of icon (source/dark/tint or glyph/color), with the CLI and the parser rejecting mixed forms, plus action panel alignment. Done in Add the object form of extension icons and align action panel icons (#949 step 3) #991
4. Remote icons through fetch_scoped, so extension icons never reach an <img> directly.
5. Store icons and README images: done in feat(cli): ship README and icon in the package for the Store #956.

Since we agree on the direction, step 1 is yours if you still want it. Tell me if you'd like to split it differently.

[BennoCrafter]

@Xoshbin yeah great! I’ll start working asap on point 1

[BennoCrafter]

#964 resolves step 1

[BennoCrafter]

@Xoshbin assign yourself to step 2! When completed I can work on step 3

[Xoshbin]

Hey @BennoCrafter

Step 2 is implemented, let me know if you can assign yourself for step 3.

[BennoCrafter]

yes please. let me first have a look at your work.

[Xoshbin]

Thank you for addressing step 3 Benno.

I can work on step 4, let me know if you would like to work on it yourself.

[BennoCrafter]

Thank you for addressing step 3 Benno.

I can work on step 4, let me know if you would like to work on it yourself.

@Xoshbin please assign step 4 to yourself. let's get this feature done!