From 13e57cfd0792311dec32efb6d1ed564b7a643a79 Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 10 Sep 2026 20:06:00 +0200
Subject: [PATCH 1/6] feat(hub-ui): render explicit SVG mask icons

---
 docs/content/8.references/4.node-api.md       |  4 +++-
 .../client/components/icons/IconifyIcon.vue   | 11 ++++++++--
 .../hub/src/client/dock-resources.test.ts     | 10 ++++++++++
 packages/hub/src/client/dock-resources.ts     |  8 ++++++++
 plugins/terminals/app/client/App.svelte       | 20 ++++++++++++++++---
 plugins/terminals/src/node/manager.ts         |  9 ++-------
 plugins/terminals/test/terminals.test.ts      |  6 ++++++
 7 files changed, 55 insertions(+), 13 deletions(-)

diff --git a/docs/content/8.references/4.node-api.md b/docs/content/8.references/4.node-api.md
index cdb6bf036..25b7f7af4 100644
--- a/docs/content/8.references/4.node-api.md
+++ b/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, or `mask:<image-url>`; light/dark pairs. |
 | `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,8 @@ 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). |
 
+The reference hub UI and terminal SPA render `mask:` icons with the surrounding text color, preserving the image's shape and opacity. 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).
diff --git a/packages/hub-ui/src/client/components/icons/IconifyIcon.vue b/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
index 7a210ccae..898a009c6 100644
--- a/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
+++ b/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
@@ -6,7 +6,8 @@ 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) : undefined)
+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
@@ -38,7 +39,13 @@ watchEffect(async () => {
 
 <template>
   <div
-    v-if="iconifyParsed"
+    v-if="maskUrl !== undefined"
+    aria-hidden="true"
+    class="w-full h-full"
+    :style="{ backgroundColor: 'currentColor', mask: `url(${JSON.stringify(maskUrl)}) center / contain no-repeat`, maskMode: 'alpha' }"
+  />
+  <div
+    v-else-if="iconifyParsed"
     v-html="iconifyLoaded"
   />
   <img
diff --git a/packages/hub/src/client/dock-resources.test.ts b/packages/hub/src/client/dock-resources.test.ts
index 301649475..2ca13fbe6 100644
--- a/packages/hub/src/client/dock-resources.test.ts
+++ b/packages/hub/src/client/dock-resources.test.ts
@@ -29,6 +29,16 @@ 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('resolves light and dark icon variants independently', () => {
     expect(resolveDockIcon({
       light: './icons/light.svg',
diff --git a/packages/hub/src/client/dock-resources.ts b/packages/hub/src/client/dock-resources.ts
index fa8634aa6..3c1446f55 100644
--- a/packages/hub/src/client/dock-resources.ts
+++ b/packages/hub/src/client/dock-resources.ts
@@ -21,6 +21,14 @@ function resolveResourceUrl(value: string, connection: DevframeConnection): stri
 
 function resolveIconUrl(value: string, connection: DevframeConnection): string {
   const url = value.trim()
+  if (url.startsWith('mask:')) {
+    try {
+      return `mask:${new URL(url.slice(5), connection.metaBaseUrl).href}`
+    }
+    catch {
+      return url
+    }
+  }
   if (!url || URL_SCHEME_RE.test(url) || url.startsWith('//'))
     return url
 
diff --git a/plugins/terminals/app/client/App.svelte b/plugins/terminals/app/client/App.svelte
index 0f845c227..bdd2efe5b 100644
--- a/plugins/terminals/app/client/App.svelte
+++ b/plugins/terminals/app/client/App.svelte
@@ -351,6 +351,20 @@
 
 <svelte:window onkeydown={onGlobalKey} />
 
+{#snippet terminalIcon(icon: string, className = '')}
+  {#if icon.startsWith('mask:')}
+    <div
+      class="shrink-0 w-1em h-1em {className}"
+      aria-hidden="true"
+      style:background-color="currentColor"
+      style:mask={`url(${JSON.stringify(icon.slice(5))}) center / contain no-repeat`}
+      style:mask-mode="alpha"
+    ></div>
+  {:else}
+    <div class="{icon} shrink-0 {className}"></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 +413,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 +476,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 +496,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>
diff --git a/plugins/terminals/src/node/manager.ts b/plugins/terminals/src/node/manager.ts
index 648f80cc6..972e9bf0a 100644
--- a/plugins/terminals/src/node/manager.ts
+++ b/plugins/terminals/src/node/manager.ts
@@ -94,17 +94,12 @@ const HUB_STATUS: Record<TerminalStatus, HubTerminalEntry['status']> = {
   error: 'error',
 }
 
-/**
- * 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 to the terminal SPA's UnoCSS classes. */
 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 {
diff --git a/plugins/terminals/test/terminals.test.ts b/plugins/terminals/test/terminals.test.ts
index 1cf1624cd..ae334d03c 100644
--- a/plugins/terminals/test/terminals.test.ts
+++ b/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')

From be142bdc7b88705d59bdb7fcd14a3a0cee5e5759 Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 10 Sep 2026 21:50:53 +0200
Subject: [PATCH 2/6] fix(hub-ui): normalize explicit mask URLs

---
 .../hub-ui/src/client/components/icons/IconifyIcon.vue    | 2 +-
 packages/hub/src/client/dock-resources.test.ts            | 8 ++++++++
 packages/hub/src/client/dock-resources.ts                 | 5 ++++-
 plugins/terminals/app/client/App.svelte                   | 2 +-
 4 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/packages/hub-ui/src/client/components/icons/IconifyIcon.vue b/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
index 898a009c6..56404264e 100644
--- a/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
+++ b/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
@@ -6,7 +6,7 @@ const props = defineProps<{
   icon: string
 }>()
 
-const maskUrl = computed(() => props.icon.startsWith('mask:') ? props.icon.slice(5) : undefined)
+const maskUrl = computed(() => props.icon.startsWith('mask:') ? props.icon.slice(5).trim() : undefined)
 const isUrlIcon = computed(() => maskUrl.value !== undefined || props.icon.includes('/') || props.icon.startsWith('data:') || props.icon.startsWith('builtin:'))
 const iconifyParsed = computed(() => {
   if (isUrlIcon.value)
diff --git a/packages/hub/src/client/dock-resources.test.ts b/packages/hub/src/client/dock-resources.test.ts
index 2ca13fbe6..01821fe6c 100644
--- a/packages/hub/src/client/dock-resources.test.ts
+++ b/packages/hub/src/client/dock-resources.test.ts
@@ -39,6 +39,14 @@ describe('dock resource resolution', () => {
     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',
diff --git a/packages/hub/src/client/dock-resources.ts b/packages/hub/src/client/dock-resources.ts
index 3c1446f55..844b6c4d6 100644
--- a/packages/hub/src/client/dock-resources.ts
+++ b/packages/hub/src/client/dock-resources.ts
@@ -22,8 +22,11 @@ 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(url.slice(5), connection.metaBaseUrl).href}`
+      return `mask:${new URL(maskUrl, connection.metaBaseUrl).href}`
     }
     catch {
       return url
diff --git a/plugins/terminals/app/client/App.svelte b/plugins/terminals/app/client/App.svelte
index bdd2efe5b..384da072e 100644
--- a/plugins/terminals/app/client/App.svelte
+++ b/plugins/terminals/app/client/App.svelte
@@ -357,7 +357,7 @@
       class="shrink-0 w-1em h-1em {className}"
       aria-hidden="true"
       style:background-color="currentColor"
-      style:mask={`url(${JSON.stringify(icon.slice(5))}) center / contain no-repeat`}
+      style:mask={`url(${JSON.stringify(icon.slice(5).trim())}) center / contain no-repeat`}
       style:mask-mode="alpha"
     ></div>
   {:else}

From 8cb970dca0e443d3c62c948b57ba6ded8cc226a7 Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 10 Sep 2026 21:54:12 +0200
Subject: [PATCH 3/6] docs(terminals): preserve icon normalization constraints

---
 plugins/terminals/src/node/manager.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/plugins/terminals/src/node/manager.ts b/plugins/terminals/src/node/manager.ts
index 972e9bf0a..d28a16e9e 100644
--- a/plugins/terminals/src/node/manager.ts
+++ b/plugins/terminals/src/node/manager.ts
@@ -94,7 +94,12 @@ const HUB_STATUS: Record<TerminalStatus, HubTerminalEntry['status']> = {
   error: 'error',
 }
 
-/** Preserve explicit masks; normalize other hub icons to the terminal SPA's UnoCSS classes. */
+/**
+ * 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)

From 6ccc2fd28e84b6e991b0d051e6f82b140327a7fa Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 10 Sep 2026 21:55:40 +0200
Subject: [PATCH 4/6] fix(hub-ui): render empty masks without image requests

---
 packages/hub-ui/src/client/components/icons/IconifyIcon.vue | 2 +-
 plugins/terminals/app/client/App.svelte                     | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/packages/hub-ui/src/client/components/icons/IconifyIcon.vue b/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
index 56404264e..4a2c3a307 100644
--- a/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
+++ b/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
@@ -42,7 +42,7 @@ watchEffect(async () => {
     v-if="maskUrl !== undefined"
     aria-hidden="true"
     class="w-full h-full"
-    :style="{ backgroundColor: 'currentColor', mask: `url(${JSON.stringify(maskUrl)}) center / contain no-repeat`, maskMode: 'alpha' }"
+    :style="{ backgroundColor: maskUrl ? 'currentColor' : 'transparent', mask: maskUrl ? `url(${JSON.stringify(maskUrl)}) center / contain no-repeat` : 'none', maskMode: 'alpha' }"
   />
   <div
     v-else-if="iconifyParsed"
diff --git a/plugins/terminals/app/client/App.svelte b/plugins/terminals/app/client/App.svelte
index 384da072e..706ca26b2 100644
--- a/plugins/terminals/app/client/App.svelte
+++ b/plugins/terminals/app/client/App.svelte
@@ -353,11 +353,12 @@
 
 {#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="currentColor"
-      style:mask={`url(${JSON.stringify(icon.slice(5).trim())}) center / contain no-repeat`}
+      style:background-color={maskUrl ? 'currentColor' : 'transparent'}
+      style:mask={maskUrl ? `url(${JSON.stringify(maskUrl)}) center / contain no-repeat` : 'none'}
       style:mask-mode="alpha"
     ></div>
   {:else}

From 9f8c99a8e5e2520dad8e93484ee761940ff15d4a Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 10 Sep 2026 21:58:21 +0200
Subject: [PATCH 5/6] refactor(hub-ui): compute mask icon styles

---
 .../src/client/components/icons/IconifyIcon.vue      | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/hub-ui/src/client/components/icons/IconifyIcon.vue b/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
index 4a2c3a307..f9cb6331a 100644
--- a/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
+++ b/packages/hub-ui/src/client/components/icons/IconifyIcon.vue
@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import type { CSSProperties } from 'vue'
 import { computed, ref, watchEffect } from 'vue'
 import { getIconifySvg } from '../../utils/iconify'
 
@@ -7,6 +8,15 @@ const props = defineProps<{
 }>()
 
 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)
@@ -42,7 +52,7 @@ watchEffect(async () => {
     v-if="maskUrl !== undefined"
     aria-hidden="true"
     class="w-full h-full"
-    :style="{ backgroundColor: maskUrl ? 'currentColor' : 'transparent', mask: maskUrl ? `url(${JSON.stringify(maskUrl)}) center / contain no-repeat` : 'none', maskMode: 'alpha' }"
+    :style="maskStyle"
   />
   <div
     v-else-if="iconifyParsed"

From 593ca84683dcf6628f0d609b1b6e3e11c6cf5b0d Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 10 Sep 2026 22:05:48 +0200
Subject: [PATCH 6/6] fix(terminals): mark class icons as decorative

---
 plugins/terminals/app/client/App.svelte | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/terminals/app/client/App.svelte b/plugins/terminals/app/client/App.svelte
index 706ca26b2..ef9477dfc 100644
--- a/plugins/terminals/app/client/App.svelte
+++ b/plugins/terminals/app/client/App.svelte
@@ -362,7 +362,7 @@
       style:mask-mode="alpha"
     ></div>
   {:else}
-    <div class="{icon} shrink-0 {className}"></div>
+    <div class="{icon} shrink-0 {className}" aria-hidden="true"></div>
   {/if}
 {/snippet}