feat(hub-ui): render explicit SVG mask icons (#382)

Co-authored-by: Anthony Fu (via agent) <reg-github-bot@antfu.me>
Co-authored-by: Anthony Fu <github@antfu.me>

Author: 3 people

docs/content/1.guide/2.devframe-definition.md

@@ -39,7 +39,7 @@ export default defineDevframe({
 
 ## Definition fields
 
-`id`, `name`, `version`, `packageName`, `homepage`, `description`, and `setup` are required; pass `importMetaUrl: import.meta.url` so [remote assets](/guide/client-assets) and declared [services](/guide/services#wire-services) resolve against the devframe's own dependencies. The remaining fields cover display (`icon`), mounting (`basePath`, `duplicationStrategy`, `capabilities`), what the devframe consumes and serves (`services`, `clientAssets`, `rpc.snapshot`), and [CLI defaults](#cli-options) (`cli`). Every field is listed in the [Node-Side API reference](/references/node-api#definition-fields).
+`id`, `name`, `version`, `packageName`, `homepage`, `description`, and `setup` are required; pass `importMetaUrl: import.meta.url` so [remote assets](/guide/client-assets) and declared [services](/guide/services#wire-services) resolve against the devframe's own dependencies. The remaining fields cover display (`icon`, [Icon values](/references/node-api#icon-values)), mounting (`basePath`, `duplicationStrategy`, `capabilities`), what the devframe consumes and serves (`services`, `clientAssets`, `rpc.snapshot`), and [CLI defaults](#cli-options) (`cli`). Every field is listed in the [Node-Side API reference](/references/node-api#definition-fields).
 
 ### Sourcing metadata from `package.json`
 

docs/content/8.references/4.node-api.md

@@ -20,7 +20,7 @@ The fields of a `DevframeDefinition`: [Devframe Definition](/guide/devframe-defi
 | `importMetaUrl` | `string` | **Recommended.** Pass `import.meta.url`, the deps resolution base: default `resolveFrom` for [remote assets](/guide/client-assets) and declared [services](/guide/services#wire-services). |
 | `homepage` | `string` | **Required.** Homepage/docs URL. |
 | `description` | `string` | **Required.** One-line summary. |
-| `icon` | `string \| { light, dark }` | Optional Iconify name or URL; light/dark pairs. |
+| `icon` | `string \| { light, dark }` | Optional Iconify name, image URL, light/dark pairs, etc. See [Icon values](#icon-values). |
 | `basePath` | `string` | Optional mount-path override. Default `/` standalone (`cli`/`build`), `/__<id>/` hosted (`vite`/`embedded`). |
 | `duplicationStrategy` | `'warn' \| 'silent' \| 'throw' \| 'duplicate'` | Hub reaction when another devframe shares this `id`. Default `'warn'`. See [Duplication strategies](/references/hub-api#duplication-strategies); standalone adapters ignore it. |
 | `capabilities` | `{ dev?, build? }` | Per-runtime feature flags. `boolean` = whole runtime; object = individual features. |
@@ -30,6 +30,20 @@ The fields of a `DevframeDefinition`: [Devframe Definition](/guide/devframe-defi
 | `setup` | `(ctx, info?) => void \| Promise<void>` | **Required.** Server-side entry point, run in every runtime. Optional 2nd arg carries runtime metadata, notably parsed CLI `flags` under `createCac`. |
 | `cli` | `DevframeCliOptions` | CLI adapter defaults. See [CLI options](#cli-options). |
 
+## Icon values
+
+The `icon` field, and every dock entry, command, and terminal icon, accept the same string forms. A `{ light, dark }` pair picks the matching variant per active color scheme, and each side takes any of these forms:
+
+| Form | Example | Rendered as |
+|---|---|---|
+| Iconify name | `ph:gauge-duotone`, `logos:nuxt-icon` | the `collection:icon` glyph, fetched from Iconify as inline SVG |
+| Image URL | `/icons/logo.svg`, `https://example.com/logo.png` | an `<img>`; relative URLs resolve against the supplying hub |
+| Data URL | `data:image/svg+xml,%3Csvg…%3E` | an inline `<img>` from the embedded data |
+| SVG mask | `mask:/icons/logo.svg`, `mask:data:image/svg+xml,%3Csvg…%3E` | an alpha mask tinted with `currentColor`, following the surrounding text color |
+| Light/dark pair | `{ light: './logo-light.svg', dark: './logo-dark.svg' }` | the variant matching the active color scheme; each side is any string form above |
+
+The reference hub UI and terminal SPA render `mask:` icons with the surrounding text color, preserving the image's shape and opacity, so a bundled monochrome SVG follows the dock's foreground color through selected and dimmed states. For a bundled SVG, use `` `mask:data:image/svg+xml,${encodeURIComponent(svg)}` ``. A mask produces one color; use an ordinary image URL for multicolor artwork. Relative mask URLs on dock entries resolve against the supplying hub's URL. Custom hub UI providers implement this string convention in their own icon renderer.
+
 ## CLI options
 
 The `cli` field's `DevframeCliOptions`: [CLI options](/guide/devframe-definition#cli-options).

docs/content/8.references/6.hub-api.md

@@ -145,7 +145,7 @@ The origin-locked `postMessage` protocol on `devframe:frame-nav`: [Shared-iframe
 
 ## Dock entry types
 
-The built-in variants of the open dock union (`DevframeDockEntryRegistry`, `@devframes/hub/types`) a hub UI provider renders: [Build Your Own Hub UI](/guide/build-your-own-hub-ui).
+The built-in variants of the open dock union (`DevframeDockEntryRegistry`, `@devframes/hub/types`) a hub UI provider renders: [Build Your Own Hub UI](/guide/build-your-own-hub-ui). Each entry's `icon` takes any of the [icon values](/references/node-api#icon-values).
 
 | Type | The hub UI provider renders |
 |---|---|

packages/hub-ui/src/client/components/icons/IconifyIcon.vue

@@ -1,12 +1,23 @@
 <script setup lang="ts">
+import type { CSSProperties } from 'vue'
 import { computed, ref, watchEffect } from 'vue'
 import { getIconifySvg } from '../../utils/iconify'
 
 const props = defineProps<{
   icon: string
 }>()
 
-const isUrlIcon = computed(() => props.icon.includes('/') || props.icon.startsWith('data:') || props.icon.startsWith('builtin:'))
+const maskUrl = computed(() => props.icon.startsWith('mask:') ? props.icon.slice(5).trim() : undefined)
+const maskStyle = computed<CSSProperties | undefined>(() => {
+  if (!maskUrl.value)
+    return undefined
+  return {
+    backgroundColor: 'currentColor',
+    mask: `url(${JSON.stringify(maskUrl.value)}) center / contain no-repeat`,
+    maskMode: 'alpha',
+  }
+})
+const isUrlIcon = computed(() => maskUrl.value !== undefined || props.icon.includes('/') || props.icon.startsWith('data:') || props.icon.startsWith('builtin:'))
 const iconifyParsed = computed(() => {
   if (isUrlIcon.value)
     return undefined
@@ -45,6 +56,12 @@ watchEffect(async (onCleanup) => {
 
 <template>
   <div v-if="failed" class="i-ph:warning-duotone w-full h-full" aria-hidden="true" />
+  <div
+    v-else-if="maskUrl !== undefined"
+    aria-hidden="true"
+    class="w-full h-full"
+    :style="maskStyle"
+  />
   <div
     v-else-if="iconifyParsed"
     aria-hidden="true"

packages/hub/src/client/dock-resources.test.ts

@@ -29,6 +29,24 @@ describe('dock resource resolution', () => {
     expect(resolveDockIcon('data:image/svg+xml;base64,abc', connection)).toBe('data:image/svg+xml;base64,abc')
   })
 
+  it('resolves mask URLs and preserves mask data through JSON transport', () => {
+    expect.assertions(4)
+    const data = 'mask:data:image/svg+xml,%3Csvg%2F%3E'
+    const icon = JSON.parse(JSON.stringify({ light: data, dark: 'mask:./dark.svg' }))
+    expect(resolveDockIcon('mask:/icons/local.svg', connection)).toBe('mask:http://localhost:5173/icons/local.svg')
+    expect(resolveDockIcon('mask:icon', connection)).toBe('mask:http://localhost:5173/__devtools/icon')
+    expect(resolveDockIcon('mask:https://example.com/icon.svg', connection)).toBe('mask:https://example.com/icon.svg')
+    expect(resolveDockIcon(icon, connection)).toEqual({ light: data, dark: 'mask:http://localhost:5173/__devtools/dark.svg' })
+  })
+
+  it('trims mask URLs and preserves empty masks without resolving the metadata URL', () => {
+    expect.assertions(4)
+    expect(resolveDockIcon('mask: ./icon.svg ', connection)).toBe('mask:http://localhost:5173/__devtools/icon.svg')
+    expect(resolveDockIcon('mask: data:image/svg+xml,%3Csvg%2F%3E ', connection)).toBe('mask:data:image/svg+xml,%3Csvg%2F%3E')
+    expect(resolveDockIcon('mask:', connection)).toBe('mask:')
+    expect(resolveDockIcon('mask:   ', connection)).toBe('mask:')
+  })
+
   it('resolves light and dark icon variants independently', () => {
     expect(resolveDockIcon({
       light: './icons/light.svg',

packages/hub/src/client/dock-resources.ts

@@ -21,6 +21,17 @@ function resolveResourceUrl(value: string, connection: DevframeConnection): stri
 
 function resolveIconUrl(value: string, connection: DevframeConnection): string {
   const url = value.trim()
+  if (url.startsWith('mask:')) {
+    const maskUrl = url.slice(5).trim()
+    if (!maskUrl)
+      return 'mask:'
+    try {
+      return `mask:${new URL(maskUrl, connection.metaBaseUrl).href}`
+    }
+    catch {
+      return url
+    }
+  }
   if (!url || URL_SCHEME_RE.test(url) || url.startsWith('//'))
     return url
 

plugins/terminals/app/client/App.svelte

@@ -351,6 +351,21 @@
 
 <svelte:window onkeydown={onGlobalKey} />
 
+{#snippet terminalIcon(icon: string, className = '')}
+  {#if icon.startsWith('mask:')}
+    {@const maskUrl = icon.slice(5).trim()}
+    <div
+      class="shrink-0 w-1em h-1em {className}"
+      aria-hidden="true"
+      style:background-color={maskUrl ? 'currentColor' : 'transparent'}
+      style:mask={maskUrl ? `url(${JSON.stringify(maskUrl)}) center / contain no-repeat` : 'none'}
+      style:mask-mode="alpha"
+    ></div>
+  {:else}
+    <div class="{icon} shrink-0 {className}" aria-hidden="true"></div>
+  {/if}
+{/snippet}
+
 {#if connCopy}
   <div class={connectionPanel('absolute inset-0 color-base font-sans')}>
     <div class="{connCopy.icon} {connectionGlyph(connCopy.spin)}"></div>
@@ -399,7 +414,7 @@
           >
             <span class={dot(statusDot(s.status))}></span>
             {#if s.icon}
-              <div class="{s.icon} shrink-0"></div>
+              {@render terminalIcon(s.icon)}
             {/if}
             <span class="truncate">{displayName(s)}</span>
             <span
@@ -462,7 +477,7 @@
                 class="flex items-center gap-2 px2 py1.5 rounded text-sm text-left op-fade hover:(op100 bg-active) transition-colors"
                 onclick={() => runPreset(p.id)}
               >
-                <div class="{p.icon || 'i-ph-terminal-duotone'} shrink-0 op-fade"></div>
+                {@render terminalIcon(p.icon || 'i-ph-terminal-duotone', 'op-fade')}
                 <span class="truncate flex-1">{p.title}</span>
                 <span class="font-mono text-xs op-mute">{p.mode === 'interactive' ? 'tty' : 'log'}</span>
               </button>
@@ -482,7 +497,7 @@
       </span>
       <span class="font-mono truncate op-fade flex items-center gap-1.5" title={`${s.command} ${s.args.join(' ')}`}>
         {#if s.icon}
-          <div class="{s.icon} shrink-0 text-base"></div>
+          {@render terminalIcon(s.icon, 'text-base')}
         {/if}
         {s.command}{s.args.length ? ` ${s.args.join(' ')}` : ''}
       </span>

plugins/terminals/src/node/manager.ts

@@ -95,16 +95,16 @@ const HUB_STATUS: Record<TerminalStatus, HubTerminalEntry['status']> = {
 }
 
 /**
- * Normalize a hub dock icon (`ph:code-duotone`, or a light/dark pair) to the
- * UnoCSS `preset-icons` class the client renders (`i-ph-code-duotone`). The
- * client can only render icons the SPA's UnoCSS build statically emitted (see
- * the safelist in `uno.config.ts`), so unknown icons resolve to `undefined`.
+ * Preserve explicit masks; normalize other hub icons (`ph:code-duotone`) to
+ * UnoCSS classes (`i-ph-code-duotone`), choosing the light variant of theme pairs.
+ * Class icons render only if the terminal SPA's UnoCSS build includes them
+ * (see the safelist in `uno.config.ts`); masks load their image URL directly.
  */
 function toIconClass(icon?: HubTerminalEntry['icon']): string | undefined {
   const raw = typeof icon === 'string' ? icon : icon?.light
   if (!raw)
     return undefined
-  return raw.startsWith('i-') ? raw : `i-${raw.replace(':', '-')}`
+  return raw.startsWith('mask:') || raw.startsWith('i-') ? raw : `i-${raw.replace(':', '-')}`
 }
 
 function defaultShell(): string {

plugins/terminals/test/terminals.test.ts

@@ -338,6 +338,7 @@ describe('@devframes/plugin-terminals', () => {
 
   describe('hub aggregation', () => {
     it('surfaces sessions contributed by other devframes as read-only entries', async () => {
+      expect.assertions(9)
       await server.close()
       const hub = createFakeHubTerminals()
       server = await startTerminalsServer({}, { hub })
@@ -364,6 +365,11 @@ describe('@devframes/plugin-terminals', () => {
       // Its output is read from the hub's streaming channel, not the plugin's.
       expect(cs?.channel).toBe('devframe:terminals')
 
+      const mask = 'mask:data:image/svg+xml,%3Csvg%2F%3E'
+      hub.update({ id: 'devframes_plugin_code-server', icon: mask })
+      const masked = await call<TerminalSessionInfo[]>(client, 'devframes:plugin:terminals:list')
+      expect(masked.find(session => session.id === 'devframes_plugin_code-server')?.icon).toBe(mask)
+
       // A stopped hub session maps onto the plugin's 'exited' status.
       hub.update({ id: 'devframes_plugin_code-server', status: 'stopped' })
       const afterStop = await call<TerminalSessionInfo[]>(client, 'devframes:plugin:terminals:list')